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TeleGUI 

A new space of services 
AT&T Confidential - 1 March 1999 
This version 15 June 1999 



Quentin Su^ord-Fraser 



With the advent of high-bandwidth 
permanent connections to the 
home* a new paradigm to 
personal communications, and even for 
personal confuting, becomes possible. In 
this new wcx-ld, the network is everything. 
The commodity is no longer hardware or 
software, but services. 



At AT&T Laboratories Cambridge, we 
have learned a great deal from the Virtual 
Networlc Computing project The VNC 
system is based on ttie cmcept of ultra- 
thin clients ^ich provide a fcamebuf fer 
connected to a display, and have some 
devices, typically a keyboard and mouse* 
for input. These clients (or *VNC 
viewers') connect to a renxite VNC server, 
which uses very low-level graphics 
primitives to draw into the viewer's 
firamebuffer, where the user can see the 
results. Typically, the server will draw a 
conventional workstation ^desktop* with 
which the user can interact and on which 
he can run staixlard applications. As an 
exan^le, with the Java version of the 
VNC viewer and the Windows versicm of 
the VNC server, I can use a web browser 
to connect to a remote PC and run 
Windows applications. 

The viewer is virtually stateless, with all 
important state stored at the server. This 
means that if you disconnect from the 
server and then reccmnect, either from the 
same place or from elsewhere, the viewer 
sinq>ly requests a screen refresh, and you 
see the desktop exactly as you left it Even 

the cursor will still be in the same place.- 

VNC viewers and servers are available for 
a wide variety of platforms, from Cray 




mainframes to PalmPilots, The VNC 
system is freely available from our wd> 
site' and is in use by hundreds of 
thousands of people world-wide. 

The VNC protocol is sufiflcienay simple 
that it could easily be einbedded in 
consumer electronics devices. This paper 
proposes that a low-level graphics protocol 
such as VNC could be fed into the home 
or business and that Hiis would provide a 
very powerful development of the 
tel^hone service as we know it. 



For the purposes of this discussion we 
might imagine the 'Communicator* device 
pictured above: a tdq)hone with its 
numeric keypad r^Iaced by a touch 
screen which could, by default, display the 
old keypad and operate like a traditional 



Seeiittp-7/www.nV 
DetaUeddocumentatiOQ on VNCs 
cperaticn is also available from here. 



telephone^. Many otber form factors are 
also possible. We might consider wall- 
mounted Communicators with larger 
screens and hands-free (^>erationt 
Communicators in^lemented as set-top 
boxes. Communicators which sit on a desk 
with a keyboard and mouse attached, or 
soitware versions ^ch run on a PC. But 
whatever the form, we imagine a device 
which is at least as ubiquitous as the 
telq>hone» and in an ideal wcu-ld* as 
ubiquitous as the light switch. 

The Communicator's coimection to the 
network might be ATM, IP or simple 
ISDN, and the VNC protocol, or 
something built on similar principles, 
would be carried alongside any voice 
traffic. The imp<Htant point here is thar 
this is not a phone with a PC m it, and it is 
not a phcHie with a wdi browser in it It is 
a phcMie with a display in it And every 
pixel of that display is driven over the 
network. We'll r^um to this point later, 
but first 1^'s consider some sinq>le 
exaxiq>les of how such a device migfht be 
used: 

• You telq)hone a business, and as an 
alternative to navigating through a list 
of voice pron^ts, you can select from 
an on-screen menu. While you are on 
hold, you might be shown information 
about the conq)any*s products, or 
about the person you will eventually 
be talking to. When you are 
connected, you mig^ see a picture or 
the business card of the person at the 
other end. 

* You don't need to remember arcane 
sequences of k^ presses to access the 
call-waiting, call-forwarding and 
similar facilities inchided with your 
telq)hone service, because you are 
pronq)ted with a friendly on-screen 
menu. 



Since Che initial version of this paper, a 
protot>pe of such adevice has been built at 
our laboratory. 



• When you buy a new Communicator, 
you don't need to program it with all 
your speed-dial numbers. The service 
provider stores those for you, and 
displays them accc»xling to your 
preferences. You just plug it in. And if 
you use your AT&T calling card in a 
ph(Mie anywhere else, you get the 
same menus that you*re used to at 
home. 

• Whra you call a friend, you might, by 
default, get a shared sketch pad on 
which you could both make notes, 
draw maps, etc. wtiile talking. 

The telq>hone occupies a different place in 
the home from the TV or the PC, and the 
applications that people will want to use 
from a device that sits on their coffee table 
oc bedside table may be very different 
from those used elsewhere. One might 
imagine a TV guide which is customised 
tcx your channels, which highli£^ your 
favourite programmes, and which shows 
low-frame-rate thumbnails of the current 
content of each video channeL Reminder 
services, directory informadon and yellow 
pages ndght aU be ^ven friendlier 
interfaces. And wouldnH it be easier to 
order pizza over the phone if you could 
lock at the menu while you were doing it? 



Why not browse?; V 



There is an obvious comparison to be 
made with the World Wide Web. Many of 
these services can already be found there, 
and it could be argued that the sensible 
thing to put into the ConmiunicatcM: is a 
web browser, not a VNC viewer, because 
a browser generally requires less 
bandwidth and because the enc^int is 
arguably the thing that knows best how to 
raider infmnation effectively onto itself. 

The bandwidth problem is a current one, 
more than a future cne. We are 
anticipating home networks many many 
times faster than the modems which are 
currently used by most users fw w^ 
surfing. We anticipate, from our VNC 
experience, that a bandwidth of-around" 
lOOldVs would make an ideal service, and 
many cable modems are now operating at 



nearly 300 times that rate. We have 
become very accustomed to saying 
••Processing power is cheap, so let's put a 
processor inside'*. I think we are entering 
a world where **Bandwidth is cheap, so 
let's use the network!" may be an e^ially 
valid assertion for many s^plications. 

Any browser, in the end, has to base its 
rendering on the width, height and colour 
capabilities of the display that the user is 
sitting in front of. Whether it is direcdy 
connected to that display, or connected via 
a network is largely irrelevant And all we 
are doing here is adding an extra level of 
indirection. It may be that when you buy 
the latest Communicator from ACME, Inc. 
you are also buying a subscription to their 
browser service* which is cqytimised for 
ttiis particular device. 

Even an sq)plication as sin^>le as a w^ 
browser will always have compatibility 
and support issues, both of hardware and 
software, when you use it as the main 
communication device for millions of 
people. And this is not only when 
downloading plug-ins for exotic formats. 
How much memory does your 
Communicator have? That win afifect how 
large a page it can download. 

To put a browser into the Communicator 
would be a bit like putting a speech 
synthesis chip into a phone. Imagine if, 
v/ben you connected to an information 
service, the information was sent to your 
phone as textual data and then ccmverted 
to audio by the chip. What happens when 
different manufacturers' phones have 
different chq>s? Qrinlien yon connect to a 
fcx-eign-language service which needs 
different phonemes? It's obviously much 
better to use the available bandwidth fcK 
direct end-to-end audio, because by going 
for the lowest common denominator you 
keep your future options opeiL 

The same applies if you have enough 
bandwidth for end-to-end graphics. 
I m a g ine if you had built a phone based 
around a w^ browser of four years ago. 
It almost certainly would not have 
supported Java, or the 'frame' facility of 
HTML, v/hxch is now used by a large 




proportion of web sites. But if all you have 
in the home are the pixels, you can still 
provide a web browsing service, but you 
can update it at will without the user 
needing to be involved. I don't like to 
imagine a world where my father mi^t 
have the same problems updating his 
phone that he has updating his PC! 

The dumber the home device, and the 
more we can coDtralise the sophisticated 
stuff, the easier the maintenance will be 
and the less we will suffer from the need 
to update the radpoints. 

The ability to enhance telephone services 
and to provi<te web access from the coffee 
table introduces a large nunlber of new 
possibilities, but this is CHily the tip of the 
icd>erg. 



f Tife "b^ f i ci^ i c at d &M0'r-!^'- 




We have often described the VNC 
protocol as being marginally higher-level 
than a VGA lead. The viewer has no 
knowledge of the semantic sUiicture of the 
data being sent to it; it just displays pixels. 
Mouse and keyboard events are sent back 
sinq>ly as coordinates and button-presses. 
In many ways, VNC singly allows you to 
use the internet as an arbitrarily long 
keyboard & monitor extension lead. 

Now imagine a business model based on 
this concept At present, in many 
specialised business areas, ccnqniters are 
bought as part of a padcage. The supplier 
installs them in your premises, with the 
particular software package in.<:taiip<i^ 



configured and ready to run. When the 
software or hardware needs upgrading, 
they come back to your office and do it fc^ 
you. Very convenient 

But how much more convenim if they 
never had to visit you to set it up in the 
first place! If ycMi could Just connect the 
monitor, keyboard and printer on your 
desk to the computer while it was still in 
their office. If they handled all your 
backups for you, an your software 
upgrades, and did it overnight or at the 
weekend when you didn't need it. If they 
had plenty of backup machines that could 
be dropped into place in a matter of 
minutes if yours died.^ With a syst^ like 
VNC over a n^wcsk as reliable as the 
phone netwcvk, this type of business 
would be possible. 

This one service provider might only 
specialise in one type of software, but that 
wouldn't matter. You would 'dial up' 
WordPerfect Inc. when you wanted to do 
some word-processing, Qualcomm when 
you wanted to read your email, and 
Netscape when you wanted to browse the 
wd>. Each of these companies would 
provide a service, very like a prenohim-rate 
phone call, and they would drive your 
screen, or part of it, while you were 
connected. Some companies might 
provide free word-processing facilities in 
exchange for a little advertising space on 
your screen, in the same way that firee 
email services currenay do on the w^. If 
you want to try out a piece of software to 
sec i^ether it's suitable for your needs, 
you don't need to go through all the 
palaver of installing it on your machine 
and uninstalling it afterwards. You just 
dial it up on your display. 

This is the ultimate in outsourcing. No 
software is downloaded to the user, there 
are no problems with the user's noachine 
behig insufficiently powerful or being 
incon^atible in some way, and there are 



^ Of course, in a real implementation, you 
probably wocdd not use a single individual 
machine per customer, but it's a good 
model! 



no opportunities for software piracy or 
viruses. This is, in fact a whole new class 
of services, and potentially a whole new 
model for the confuting business. 



Here are some interesting starting points 
for discussion. None of these would need 
to be decided immediately. One big 
advantage of dumb endpoints is that many 
decisions can be delayed and inq>lemented 
later - they don't have to be in the device 
from the outset 

1. Do an phones in one house display the 
same thing, or are they effectively 
s^arate lines? 

2. Do mbbiie^intethered phones include 
a display? If it's in the hands^ you 
can't see it while talkmg. If it's on the 
wall, it might want to display the 
session of die nearest handset, and so 
would need to know which that is. 
Maybe the display should also be 
mobile. 

3. Do the display devices in the 
Communicator also (q)erate other 
household electrcRiics? Can you use 
them to program your burg^ alarm, 
your video and your microwave? 
These devices would not then need 
expensive displays of their own, but 
might need to be connected to a home 
•exchange' (ATM switch?). You 
could even, then, have another class of 
services where remote 'experts' dial in 
to your home devices and configure 
ttiemforyou. 

4. Lastly, do we expect the 
CommunicatcH' to display video? This 
is certainly possible. And would there 
be an option of high-quality audio so 
that it could become an extension of 
the hi-fi system and a iq)lacement for 
the radio? 

These questions are an related to the user's 
experience. There are, of course, plenty of 
issues which the service providers would 
also have to tackle, such as security, 
confidentiaUty, and reliabinty. Anocation 



m m 



of processing power to drive the devices 
might also be an issue* bat if the netwcMrk 
is in place and the netwcxk is leUable* then 
many issues can be decoupled from the 
provision of the netwoik and opened up to 
the maikeL As a user, if noty web browser 
is too slow I siii^>ly dial up another one. 
As a provider, if too many users want to 
connect to my service at ooce then I just 
buy in more processing power from 
another company and forward my 
connections there in the same way that 
electricity providers cope with regional 
surges in demand. 



Summary ^ „ , 



Most businesses dqpend heavily on the 
telq>hone networic and are, in effect, 
tmable to operate without it. The 
challenge is to make a hisfh-bandwidtb IP 
network which is as reliable. If this can be 
achieved, then suddenly your external 
connectivity becomes nxHe dependable 
than your internal connectivity. Most 
corporate conqmter networks suffer Irom 
substantial downtimes when compared to 
the public telqihone network. These days, 
in fact, it is probably not actually the 
*netw(Kk' which has the problem. 



COTporate downtime is more likely to 
come from problems with the servers (eg. 
hardware and software upgrades) than 
with the connections to them. The question 
is, can a public netwcxk service do better? 

The company which can first bmld an 
affordable wide-area network which is 
reliable and fast enough to be, in effect, 
the connection between a user's monitor 
and his CPU, has the potential 
dramatically to alter the business and 
computing world. 

This does not necessarily mean Uiat the 
connection has to be as reliabie as a VGA 
lead, but it does mean that the combination 
of local devices, renxHe services, and the 
link between them must be demonstrably 
as reliable and cost-effective as the PC 
connected to a corporate netwcHk. This, I 
believe is achievable, if the customer 
equq)ment is kq>t single, and if there is 
free and open conq>etition in the service- 
provision market. 

And at the very least we ought to be able 
to inqprove the user interface of the 
tel^hone system! 
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The so-called network computer (NC) aims to give users access 
to centralized resources firom simple, inexpensive devices. 
These devices act as dienU to more powerful server machines 
that are connected to the netwodc and provide applications, data, and 
storage for a user's preferences and personal customizations. We have 
taken this idea a stage further. In the virtual network computing 
(VNQ system, server machines su|^iy not only applications and data 
but also an entire desktop environment that can be accessed from any 
Internet-connected machine using a simple software NC. Whenever 
and wherever a VNC desktop is accessed, its state and configuratton 
(right down to the position of the cursor) are exactly the same as when 
It was last accessed. 

In contrast to many recent Internet applications, which have 
focused on giving users access to resources located anywhere in the 
world from their home computing enviroiunents, VNC provides 
access to home computing emdronments from anywhere In the 
world. Members of the OUvettI & Oracie Research Laboratory 
(ORL) use VNC to access their persona] Unix and PC desktops fiom 
any office In our Cambridge building and from around the world on 
whatever computing infrastnxrture happens to be available — Includ- 
ing, for example, public Web-browsIng terminals in airports. VNC 
thus provides mobile computing without requiring the user to cany 
airy device whatsoever. In addition, VNC allows a single desktop to 
be accessed finom several places simultaneously, thus supporting apf^ 

*An(4r Hopper b 8l» affilMM w«i Cant«)ndgo tinner^ 
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THE VNC PROTOCOL 

The technology underlying the VNC system is a simple pro- 
tocol for remote aoc» to graphical user Intedaoes. It works 
at the firamebuffer level and therefore aj^Ues to all operating 
systems, windowing systems, and applications — indeed to any 
device with some form of communications Hnk. The proto- 
col will operate over any reliable transport such asTCP/IP. 

The endpoint with which the tser Interacts (that Is. the 
display and/or input devices) is called the VNC client or 
viewer. The endpoint where changes to the framebuffer orig« 
inate (that is, the windowing system and applications) is 
known as the VNCser¥er{set Figure 1). 

VNC is truly a *thin-cllent* system. Its design makes very 
few requirements of the client, and therefore simplifies the 
task of creatii^ clients to run on a wide range of hardware. 

A Single Graphics Primitive 

The display side of the protocol Is based on a single graphics 
primitive: 

Put a rectangle of pixel data at a given X, y position. 

At first glance this might seem an Inefficient way to draw 
some user interface components. However, allowing various 
encodir^ schemes for the pixel data gives a large degree of 
flexibility in trading off parameters such as network band- 
vkddth, client drawing speed, and server processing speed. 

The lowest common denominator is the so-called raw 
encodii^. where the pixel data for a rectar^ is simply sent In 
left-to-rigbt scanline order. An VNC cUents and servers must 
support this erKXxiing. However, the encodings actually tsed 
on a given connection can be negotiated according to the 
capabilities of the server and client and the connection 
between them. 

For example, copy-iectan^e eocodipg^ very simple and effi- 
cient, and can be used when the client already has the same 
pixel data elsewhere in its framebuffer. The encoding on the 
wire is simply an j;jrooardinate. This gives a position In the 
framebufTer from which the dient can copy the rectangle of 
lteldaca.Thisencodit|gbty{ricaliyused when the user iiioves 
a window across the s creen or scrolls a window's contents. 

Most clients will support copy-rectangle encoding, since 
it Is generally easy to implement, saves bandwidth* and Is 
likely to be faster than sending raw data again. However, In 
a case where a client cannot easily read back from its frame- 
buffer, the client could specify that it should /toT be sent data 
encoded this way. 

A typical workstation desktop has large areas of solid 
color and texL One of our most effective encodings takes 
advantage of this phenomenon by describing rectangles con- 
sisting of one majority (background) color and "sub-rectan- 
gles' of difTersnt colors. There arc numerous other possible 
schemes. could use a JPEG encoding for efllclent trans-. . 
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Figure 1. VNC architecture. 



mission of still images or an MPEG encoding for moving 
images. A pixel-data caching scheme could ^Identiy encode 
mult^le oocunenoes of the same text character by referrlr^ 
to the first occurrence. 

Adaptive Update 

A set of rectangles of pixel data makes a AaraebuSer update 
(or simply, updat^ . An update represents a change from one 
valid framebuffer state to another. In this sense, an update 
Is similar to a frame of video. It dlffm, however, in that It 
usually affects only a small area of the framebuffer. Each rec- 
tangle may be encoded using a different scheme. The server 
can therefore choose the encoding most appropriate for the 
particular screen content being transmitted and the avail- 
able network bandwidth. 

The update protocol Is demand-driven fay the dient. That 
is, an update is only sent by the server in re^xmse to an ex{^ic- 
it request from the dient. An screen changes since the client s 
last request are coalesced Into a single update. This gives the 
protocol an adaptive quality: the slower the client and the net- 
work, the tower the rate of updates. On a fast network, for 
example* as the user dra^ a window across the screen it will 
move smoothly, being drawn at afl the intermediate po sl tiCTis. 
On a slower link — for example, over a mixiem — the client 
will request updates less frequently, and the window win 
qipcar at fewer Qfthesepodt f orisLTte means tiiat the dlqday 
wni readi Its final state as quickly as the network bandwidth 
will allow, thus maximizing the speed of interaction. 

Inptit 

The input side of the VNC protocol is based on astandard 
workstation model of a keyboard arxl multibutton pofritirig 
device. The dient sends Input events to the server whenev- 
er the user presses a kQr or pointer button, or moves tlie 
pointing device. Input events can also be syntiiesized from 
other nonstandard I/O devices. On the Videotile. for exam- 
ple, a pen-based handwrltirig recognition engine generates 
keyboard events. 

Connection Setup ai%d Shutdown 

To establish a dieni-server connection, the server first requests 
authentication from the dient, using a challenge-response 
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Rgure 2. A varie^ of desktops being accessed from diCTerent viewen: (a) a Unix desktop from 
a Windows viewer, (b) a Windows 95 deslctop from an X viewer, (c) a Unix desktop frt>m a 
Java applet within Internet E]q>kMer, and (d) a Windows desktop using Netscape on Unix. 



scheme; the client typically requires the user to enter a pass- 
word at this point- The server and client then exchange mes- 
sages to negotiate deslctop size, pixel format, and encoding 
schemes. The client requests an update for the entire screen, 
and the session begins. Because of the stateless nature of the 
client, either side can dose the connection at any time vdth- 
out adverse consequences. 

VIMC Viewers 

In day-to-day use, we prefer the more descriptive term 
Kfewcr to the rather overloaded word client Writing a VNC 
viewer is a simple task, as Indeed it should be for any thin- 
client system. It requires only a reliable transport (usually 
TCP/IP), and a way of displaying pixels (either writing 
directfy to the fraxnebuffer or going through a windowing 
system). 

We have written viewers for all the networked display 
devices available at ORL. These include the Videotile (the 
original VNC viewer), an X-based viewer (which runs on 
Solaris, Linux, and Digital Unix workstaUons). a Win32 
viewer that runs on Windows NT and 95. and a Java applet 
that runs on any Java-capable browser (including Suns 
JavaStadon). Members of our lab use these viewers on a daOy 
basis to access their personal computing environments. 



The images in Figure 2 
show a variety of X and Win- 
dows deskt[^ being accessed 
from both Java and native X 
and Windows vieweis. 

VNC Servers 

Writing a VNC server Is 
slightly harder than writing 
a viewer. Because the proto- 
col is designed to make the 
client as simple as possible, 
it is usually up to the server 
to perform any necessary 
translations (for example, 
the server must provide 
pixel data in (he format the 
client wants). We have writ- 
ten servers for our two main 
platforms. X (that is, Unix) 
and Windows NT/95. 

The X-based server was 
the lifst one we developed. A 
single Unix machine can run 
a ntmiber of VNC servers 
for different users, each rep- 
resenting a distinct VNC 
desktop. Each de^op is like 
a virtual . X display, with a 
root window on which several X applications can appear. 

The Windows VNC server was a little more difficult to 
create. Windows has fewer places to insert hooks into the sys- 
tem to monitor dl^l^ updates, arxl the model of multiuser 
operation is less clearl>' defined. Our current server simply 
mirrors the real display to a remote client, which means that 
only a single VNC deslctop is available from any one PC. 

The X-based server, the X >dewer, the Win32 server, and 
Win32 ^ewer can all fit on a single floppy disk. 

We have also created "thin* servers which produce dis- 
plays other than desktops, udng a simple toolklL A *VNC 
CD player.* for example, generates a CD player user Inter- 
face using VNC directly without any reference to a win- 
dowing system or framebuffer (see figure 3 on the following 
page). Such servers can run on very simple hardware, and 
can be accessed from any of the standard VNC viewers. 

ANY USER INTERFACE, ANYWHERE 

At ORL, we have used VNC to add mobility to woricstation 
GUIs, where the oonc^ of at least some form of remote inter- 
action b not new. But the protocol's simplidly oouM aDow it to 
be used on a much wider range of hardware. Consumer elec- 
tronics devices, such as CD players , usually have a hi ghty spe- 
cialized user interface and typically employ customized phys- 
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Virtual Network Computing 



Some recent changes: 
Macintosh software updated to Beta 2 - new documentation soon- 1 1/6/99 
Experimental Amiga server • see the contribs pages- 10/6/99 
Geos, Netwinder & NetBSD info added to the contribs pages- 27/4/99 
VNC under new ownership! - 4/2^9 
Note: The FAQ and some other bits of the documentation are 
constantly being updated. We onJy record major changes here. 

What is VNC? - A practical introduction 

VNC stands for Virtual Network Computing. It is, In essence, a remote 
display system which allows you to view a computing 'desktop' 
environment not only on the machine where It is running, but from 
anywhere on the Internet and from a wide variety of machine 
architectures. 




The VNC system aflows you to access the same desktop 
from a wide variety of platfonns. 
Many of us, for example, use a VNC viewer running on a PC on our 
desks to display our Unix environments which are running on a large 
sender In the machine room downstairs. 

What makes it different from other systems? 
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VNC screenshots 

These shots show very simple desktops being accessed from a number 
of different platfonns. Click on the thumbnails for larger Images. 



n X desktop being viewed from a native PC viewer. 



An X desktop being viewed from 
Microsoft Internet Explorer on a PC. 





A Windows desktop being viewed from a native X viewer 



Windows desktop being used from within Netscape 
i a Unbc machine. 



Unix desktop being accessed 
rom a Madntosh using Java. 




A Unix desktop being accessed from a native Macintosh viewer. 



Windows desktop being accessed from a Macintosh 
sing Java. 




Por comments, feedback, etc, please see the 'Keeping in touch' page 
Copyright 1 999 - AT&T Laboratories Cambridge 
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Getting Started with VNC 

VNC consists of two types of component. A server, wfiich generates a 
display, and a viewer* which actually draws the display on your screen. 
There are two important features of VNC: 

• The sender and the viewer may be on different machines and on 
different architectures. We expect the most common use to be the 
display of a Unix X desktop on a PC, for example. The protocol which 
connects the server and viewer is simple, open, and platform- 
independent. 

• No state is stored at the viewer. Breaking the viewer's connection to the 
server and then reconnecting will not result in any loss of data. 
Because the connection can be remade from somewhere else, you have 
easy mobility. 

So, to get started with VNC you need to run a sender, and then connect to it 
with a viewer. Get the packages for the platforms you use from the download 
page, if you havent already, and install them. The current VNC software 
requires a TCP/IP connection between the server and the viewer, though 
there is no reason why the software couldn't be modified to use, for example, 
RS232 or Rrewire. We have internal versions that use other network 
transport layers. But for now you'll need to know the name or the IP address 
of the server machine. 

Most people will be running either a Unix server or a Windows server, though 
similar principles will apply to other platforms. 
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Running a viewer 

When you run the viewer, you need to specify the name of the server and the 
number of the desktop. If, for example, you have started a server as display 2 
on a machine called 'snoop/, you can start a viewer for It by typing: 

vncviewer snoopy: 2 
With the Windows viewer, you can run it from the command line, but you wfll 
more typically mn it from the VNC group on the Start Menu. In this case, you 
will be prompted for the host name and display number 




Enter It and dick OK, and you will be prompted for your password, after 
which you should see the remote display. (If you are connecting to a 
Windows or Mac server, the display number will be 0, unless you have 
expRcitiy changed it). 

If the machine running the server does not have a proper DNS entry, you 
probably wont be able to use the name and wili have to replace snoopy: 
wth something like 192.168.1.2:2. You can get round this on most 
platforms by creating a 'hosts* file which maps names onto IP addresses. 
Consult your local gum for help with this. 
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Usmg a web browser as a viewer 

The VNC servers also contain a small web server. If you connect to this with 
a web browser, you can download the Java verston of the viewer, and use 
this to view the server. You can then see your deskloo from any 




^ display 2 on machine 'snoopy*, you woi^^int your web browser at: 
http;/ /snoopy: 5802/ 
The applet will prompt you for your password, and should then display the 
desktop. 



That* s it! For more details see the documentation . The answers to lots of 
common questions can be found in the FAQ . 



For comments, feedback, etc, please see the 'Keeping in touch' page 
Copyright 1 999 - AT&T Laboratories Cambridge 
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VNC documentation 

Note: A detailed paper about VNC can be found as: 

Tristan Richardson, Quentin Stafford-Fraser» Kenneth R. Wood & 
Andy Hopper, "Virtual Network Computing". IEEE Internet 
Computing , Vol.2 No.1 , Jan/Feb 1 998 pp33-38. 

You can download it in Acrobat fonmat here (760k). 

The following documentation assumes a basic familiarity with the terms 
and components used in VNC. See 'What is VNC? ' and 'Getting Started' 
for introductory information, and the Frequently Asked Questions for 
common queries. 

For a quick oven^iew, you can download versions of the VNC Video . 
See also 'Whaf s new in the VNC packages? 
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VNC -How it works 

The VNC Protocol 

The VNC protocol is a simple protocol for remote access to graphical 
user interfaces. It Is based on the concept of a remote framebufferor 
RFB. In the past we have tended to refer to the VNC protocol as the 
RFB protocol, so you may have seen this term in other publications. 
The protocol simply allows a server to update the framebuffer displayed 
on a viewer. Because it works at the framebuffer level it is potentially 
applicable to all operating systems, windowing systems and 
applications. This includes X/Unix. Windows 3.1/95/NT and Macintosh, 
but might also include PDAs, and indeed any device with some form of 
communications link. The protocol will operate over any reliable 
transport such as TCP/IP. 



VNC server VNC viewer 




This Is truly a "thln-dient" protocol: it has been designed to make very 
few requirements of the viewer. In this way, clients can run on the 
widest range of hardware, and the task of implementing a client is 
made as simple as possible. 

Rectangular updates 

The display side of the protocol is based around a single graphics 
primitive: "put a redangle of pixel data at a given x,y position" . This 
might seem an Inefficient way of drawing arbitrary user interface 
components. But because we have a variety of different encoding 
schemes for the pixel data, we can select the appropriate scheme for 
each rectangle we serul, and make the most of network bandwidth, 
client drawing speed and server processing speed. 

The lowest common denominator is the so-called raw encoding, where 
the rectangle is sfn>ply pixel data sent In left-to-right scanline order. 
All clients and servers must support this encoding. However, the 

encodings actually used on any given VNC connection can be . 

negotiated acconfing to the abilities of the sender, ttie client, and the 
connection between the two. 



"«>.flfc rnnv ••Ar*«>-r»?A fmcodlnq, for example, is very simple arxl efficient 




coordinate giving the position from whk^the client can copy the 



may only require a few bytes. Most clients wilt support this encoding, 
since it is generally simple to Implement arKi saves bandwidth. 

A typical workstation desktop has large areas of solid cok>ur and of 
text Some of our most effective encodings take advantage of this by 
efficientty describing rectangles consisting of one majority 
(background) colour and 'sub-rectangles* of different colours. There 
are numerous other possible schemes. We might use a JPEG 
encoding for still images or MPEG for efficient transmlssk>n of moving 
images. An encoding which uses some kind of caching of pixel data 
would be good for rendering text, where the same character is drawn 
in the same font multiple times. Subsequent occurrences of the same 
character would be encoded simply by reference to the first 
occurrence. 

Adaptive update protocol 

A sequence of these rectangles makes a framebuffer update (or simply 
update). An update represents a change from one valid framebuffer 
state to another, so In some ways is similar to a frame of video, but It is 
usually only a small area of the framebuffer that will be affected by a 
given update. Each rectangle may be encoded using a different 
scheme. The server can therefore choose the best encoding for the 
particular screen content being transmitted and the network bandwidth 
available. 

The update protocol is demand-driven by the client That is, an update 
is only sent by the server in response to an explicit request from the 
client. This gives the protocol an adaptive quality. The sfower the client 
and the network are, the lower the rate of updates becomes. Each 
update incorporates an the changes to the 'screen' since the last client 
request With a slow client and/or network, transient states of the 
framebuffer are ignored, resulting in reduced network traffic and less 
drawing for the dient This also improves the apparent response 
speed. 

Input protocol 

The input side of the protocol is based on a standard workstation nxxlel 
of a keytx)ard and multi*button pointing device. Input events are sent 
to the server by the client whenever the user presses a key or pointer 
button, or whenever the pointing device is moved. These input events 
can also be syntheslsed from other rK>n-standard I/O devices. On our 
Videotile , for example, a pen-based handwriting recognition engine 
generates keyboard events. 

Connection Setup and Shutdown 

When the connection between a client and a server is first established, 
the server begins by requesting authenticatfon from the dient using a 
challenge-response scheme, which typically results in the user being 
prompted for a password^t the client - end. — The server and clienttherr 
exchange messages to negotiate desktop size, pixel fomiat and the 
encoding schemes to be used. The dient then requests an update for 
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ations such as dragging or 
changes to the screen. 



the entire screen, and the session begins. Because of the stateless 
nature of the client, either side can dose the connection at any time 
without adverse consequences. 

VNC Clients 

Writing an VNC viewer is a simple task, as It should be for any 
thin-dient system. It requires only a reliable transport (usually TCP/IP), 
and a way of displaying pixels (either directly writing to the framebuffer. 
or going through a windowing system). 

We have clients for all the networked display devices we have 
available at our lab. This includes the Videotile (the original RFB 
client), an X-based client (which runs on Solaris, Linux and Digital 
Unix woricstations), a Win32 client which runs on Windows m and 95, 
a Macintosh dient, and a Java client which runs on any 
Java-capable browser (including Sun's JavaStation). Members of our 
lab use these clients on a dally basis to access their personal 
computing environments. 

VNC Servers 

Writing an VNC sender is slightly harder than writing a client for a 
number of reasons. The protocol is designed to make the client as 
simple as possible, so it Is usually up to the seiver to perfomi any 
necessary translations. For example, the server must provide pixel data 
in the format the dient wants. We have senders for our two main 
platfonns, X (i.e. Unix) and Windows NT/95. 

A Unix machine can run a number of Xvnc sen^rs for different users, 
each of which represents a distinct VNC desktop. Each VNC desktop 
is like a virtual X display, with a root window on which several X 
applications can be displayed. 

The Windows server (WinVNC) is a imie more difficult to create, 
because there are fewer places to insert hooks Into the system to 
monitor display updates, and a less deariy-defined model of multiuser 
operation. Our cunrent server simply min-ors the real display to a remote 
dient, which means that the server is not •multiuser'. It does, however, 
provide the primary user of a PC with remote access to their desktop. 
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We have also created simple servers which produce displays other 
than desktops, using a simple toolkit A "VNC CD player*, for example, 
generates a CD player user Interface using the protocol directly 
without any reference to a windows system or framebuffer. Such 
servers can run on very simple hardware, and can be accessed from 
any of the starKlard viewers. 
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9 X-based VNC server 

Make sure youVe read 'Getting Started' for introductory information. 

Xvnc is the Unix VNC server, wtiich is based on a standard X server. 
Applications can display themselves on it as if it were a nonmal X 
display, but they will actually appear on any connected VNC viewers 
rather than on a physical screen. 




VNC viewer 



So Xvnc is really two servers in one. To the applications It is an X 
server, and to the remote VNC users it is a VNC server. By convention 
we have arranged that the VNC server display number will be the same 
as the X server display number, which means you can use eg. 
snoopy : 2 to refer to display 2 on machine 'snoopy* in both the X worid 
and the VNC world. 

Normally you will start Xvnc using the vncserver script, which is 
designed to simplify the process, and which is written in Pert. You can 
edit this to suit your preferences and local conditions. We recommend 
doing this rather than running Xvnc directly, but Xvnc has essentially the 
same options as a standard X server, with a few extensions. Running 
Xvnc -h will display a list. 

As mentioned in Getting Started , vncserver can be run with no options 
at ail. In this case it will choose the first available display number, start 
Xvnc as that display, and run a couple of basic applications to get you 
started. You can also specify the display number, in which case it will us 
that number if it is available and exit if not eg: 

vncserver : 13 



Run with the -help argument to see the other options. The important 
ones are as follows: 




-ncune name _ 

Each desktop has a name wh^^pay be displayed by the 
viewer. It defaults to X but y<MEi change it with this option, 
-geometry width xheight 

Specify the size of the desktop to be created. By default this 
wilt be slightly smaller than your current X display, if set, 
otherwise 1024x768. 
-deptih depth 

Specify the pixel depth in bits of the desktop to be created. By 
default this will be the same as your cunrent X display, if set. 
otherwise 8. 
-pixelfonoat format 

Specify pixel fomnat for server to use (BGRnnn or RGBnnn) 

In general, you can specify standard X server arguments to vncservei; 
and they will be passed through to Xvnc Again, xvnc -help will list its 
options, including:. 

-economic trans late 

The server normally uses a lookup table for translating pixel 
values when the viewer requests a different format from the 
native one used by the server. This can use up to 256Kbytes 
per connected viewer, so if you have many viewers you may 
wish to specify this option which will save memory at the 
expense of a little bit of speed. Only relevant for 16-bit-deep 
desktops, 
-cc n 

Sets the colour Visual dass used by the server. Some X 
appltcatkms doni cope too well with the TrueColor visual 
normally used by an 8-bit-deep Xvnc. You can nr>ake the 
server use a Pseudocolor visual by specifying -co 3. 

The script -/.vnc/kstartup is executed after the sender starts, if you want 
to change the window manager used in your VNC desktop, for example, 
this is where you should do it. 

The server also writes log files in the -/.vnc directory. These can be 
useful for tracking down configuration problems and startup errors. 



^go back to documentation 



Foroomments, feedback, etc please see the 'Keeping intouch' page 
Copyright 1999 • AT&T Laboratories Cambridge 



• WinVNC can now be run from the ^^^lenu. Alternatively, you 
can use the Start->Settings->Taskl^H^nu to add a shortcut to 
your Startup group, which will cause WinVNC to be run every time 
you log in. 

After some initial tests, you may wish to run WinVNC as a service. See 
below for more infonmation. 

Using WinVNC 

On starting, WinVNC will add a small, green version of the VNC Icon to 
the system task bar. Cricking on this icon with the right mouse button will 
cause a menu to be displayed, with the foltowing options on ft 



• Properties - This will cause the Properties dialog to be displayed, 
allowing the user to change various WinVNC parameters. 

• iGll All Clients - This will disconnect all cun-ently connected clients 
from the server. 

^ Close - Shutdown the server. 

Moving the mouse over the Icon should cause the IP addresses of the 
kxal machine to be displayed, if they can be discovered at that time. 

You can connect to the server from another machine using a VNC 
viewer, as described in the Getting Started page. 

WinVNC Properties 

The following options are available from the Properties dialog. 
Incoming Connections 



• Accept Socket Connections - The server nonmally accepts direct, 
socket*based connections from the vncviewer program. Clearing 
this tick-box disables direct connection to WinVNC, so that only the 
CORBA interface used by our Internal version may be used to start 
a connection. (See AT&T internal version info). For the public 
version, clearing this will disable any incoming connections. 

^ Display Number - This allows the user to specify the display 
number whk:h the server will use. There is normally no need to 
change this from the default of zero. 

• Auto - This tick box indicates to WinVNC whether it shoukJ use the 
display number spedfied in the Display NunrU>er box, or whether it 
should use the first display number not already in use on the server 
machine. 

• Password - Incoming connections must be authenticated to verify 
that the person connecting Is allowed to connect to this machine. 
This text box allows your password to be specified for 
authentk:ation. 

• Disable RerrK>te Keyl>oard & Pointer - Any new incoming 
connectk>ns %vin be able to view the screen but not send any input. 

Update Handfing 

Note that clicking in a window will generally cause it to be updated, so If - 
you have certain applications which dont update very well, try thisi The 
- .^.j^*. f^^ir.^ eoH«^^ Ko rfoht ones for most oeople, 
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WinVNC - The Windows NT VNC server 

WinVNC is a VNC server that will 
allow you to view your Windows 
desktop from any VNC viewer. 
Because Windows in its present, 
standard incarnation, only supports a 
single graphical user being logged in 
at any one time, WinVNC malces the 
existing desktop of the PC available 
remotely, rather than creating a separate desktop as happens with the 
Unix sender It is only fair to emphasise this: VNC does not make an NT 
machine into a multi-user server in the same way that Citrix-based 
software, for example, does. A single NT machine can therefore be 
accessed by multiple users, but if they all connect at the same time they 
will all see the same desktop! 

On the other hand, WinVNC will run on Windows 95, Windows98, 
Windows NT 4.0. Windows 2000 and on any future Win32-based 
systems, without the need to replace any system files or run any 
OS-specific versions of the program. It is a standard appHcation that can 
be run from the Start... menu and closed down Just as easily. 

WinVNC can also be run as a service, which means that you can log in 
renx>tely, do some work, and tog out again. See below for more details. 

And, of course, WinVNC is free. We hope that making the source code 
available will enable programmers who know more about the internals of 
Windows than we do to suggest improvements to any and all aspects of 
WinVNC. 

If you havent yet read the 'Getting Started' page, you might like to do 
that first to give you the general concepts. 

Installation 

WinVNC is fairly simple to install and even easier to use: 



• Run the WinVNC setup program. 

• Opfionally. install the default VNCHooks registry settings by 
selecting Install Default Registry Setb'ngs from the WinVNC folder in 
the Start menu. This will install the default hooks settings, which are 
tweaked to cope with some common, uncooperative applications, 
such as the dock. See later for more information about the registry 
settings. 



► ^ WtnVNC can now be run from the Sj^^enu. Alternatively, you 
can use the Start'->Settings->Taskbl^^nu to add a shortcut to 
your Startup group, which will cause WinVNC to be run every time 
you tog in. 

After some initial tests, you may wish to run WinVNC as a service. See 
below for more information. 

Using WinVNC 

On starting, WinVNC will add a small, green version of the VNC icon to 
the system task bar. Clicking on this icon with the right mouse button will 
cause a menu to be displayed, with the following options on it 



• Properties - This will cause the Properties dialog to be displayed, 
allowing the user to change various WinVNC parameters. 

• Kill All Clients * This will disconnect all currently connected clients 
from the server. 

• Close - Shutdown the server. 

Moving the mouse over the Icon should cause the IP addresses of the 
tocal machine to be displayed. If they can t>e discovered at that time. 

You can connect to the server from another machine using a VNC 
viewer, as descn'bed in the Getting Started page. 

WinVNC Properties 

The following options are available from the Properties dialog. 
Incoming Connections 

• Accept Socket Connections - The server normally accepts dir^. 
socket-based connections from the vncviewer program. Clearing 
this tick-box disables direct connection to WinVNC, so that only the 
CORBA interface used by our internal version may be used to start 
a connection. (See AT&T internal versk>n info). For the public 
versk>n, dearfrig this will disable any incoming connecKorvs. 

• Display Number * This allows the user to specify the display 
number which the server will use. There is normally no need to 
change this from the default of zero. 

• Auto - This tick box indicates to WinVNC whetfier rt should use the 
display number specified in the Display Numt>er box, or whether it 
should use the first display number not already In use on the server 
machine. 

• Password - incoming connections must be authenticated to verify 
that the person connecting is allowed to connect to this machine. 
This text box alk)ws your password to be specified for 
authentk^ation. 

• Disable Remote Keyboanj & Pointer - Any new Incoming 
connections will be able to view the screen but not send any input. 

Update Handling 

Note that cGcking in a window will generally cause it to be updated, so if 
you have certain applications which dont update very well, try this! The 
default uodate handfing settings should be the right ones for most people, 
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Why are we giving it away? 

We have be^h using thin-dient systems at our lab for severed years and 
have found them very useful. We hope that there might be others out 
there who will find VNC useful, port tt« find any bugs in it, and give us 
feedback. 

When we made our high-perfonnance CORBA implementation, 
omniORB, avediable recently, it was exceedingly popular and so' we are 
releasing VNC on the same terms and conditions: those of the GNU 
General Public License . 

We believe that systems based on stateless endpoints have many 
advantages, particuiarty for users who frequently move at)OUt within one 
building or the local area, because of the seamless mobility which 
comes from maintaining all the state at the server. And with our Java 
client, these mobile workers can access their email etc from anywhere in 
the world. But VNC is also useful for the enthusiast at home who has a 
Windows and a Linux machine but only one monitor. 

The initial release contains this documentation, binaries for several 
platforms, and full source code. It is distributed in the hope that it may 
be useful but without any warranty, explicit or implied. 



For comments, feedback, etc, please see the 'Keepfaig in touch' page 
Copyright 1999 - AT&T Laboratories Cambridge 



unless you have applications which cau: 




iblems. 



^ Poll Full Screen • Some applications are inconfipatible with the 
methods currently used in WinVNC to trap screen updates. For this 
reason, it is sometimes useful to be able to poll the entire screen in 
order to check for changes, sacrificing performance for accuracy. 

© Poll Foreground Window - Polling only the currently selected 
window for changes is less CPU intensive than full-screen polling 
and often gives similar results, for example when using the 
Command Prompt, which is not normally compatible with WinVNC. 

• Poll Window Under Cursor- A variation on Poll Foreground 
Window, this option causes the window under the mouse cursor to 
be polled for changes. Both options may be enabled simultaneously 
if required. 

• Poll Console Windows Only - When this option is set, the only 
windows which will be ever be polled are Command Prompts. This 
wortcs well in conjunction with Poll Window Under Cursor, to use 
polling only when the cursor is over a console window. 

• Poll On Event Received Only - When this option is ^et, the screen 
will only be polled for updates when a mouse or keyboard event is 
received from the remote client. This is provided for low bandwidth 
networks, where it may be useful to control how often the screen is 
polled and changes sent. 

The user's settings are saved into tiie user-specific section of the 
registry when WinVNC quits, meaning that they will be used next time 
you run WinVNC. 



WinVNC can now be made to run as a service proce^ under bo\h 
Windows NT and Windows 95, by following the instructions outiined 
below. You can also send Ctri-Alt-Del to the server, allowing you to 
unlock a locked workstation, fbrexample. when WtnVNCis amningasa 
service on NT. The foOowing leatures' should also be pointed out 

Windows NT features': 

• There will be one password for the machine, rather than one per 
user. 

• The system tray teon Is not always correctiy displayed, so you 
wont always be able to teU whether someone else is connected 
except by the fact that things work more slowly. 

Windows 95 ^features': 

• Whether or not the VNC password is set per-machlne or per-user 
depends on the settings in the Passwords section of the Control 
Panel. If Win95 is set to use a different set of registry values for 
each user then when a user logs in, the password will change from 
the per-machine VNC password to that user's VNC password. If 
Win95 is set to use the same settings for all users then the 



Running WinVNC as a service 



General features for both Windows NT an^Vindows 95: 



• Anything which causes the Windows VNC server to change screen 
resolution will also cause all viewers to be disconnected, and you'll 
need to reconnect. 

^ When WInVNC Is running as a system service, no user-level 
copies can be run at the same time. 

Here's how to get it running as a service, assuming youVe already 
installed it. 

1 . Windows NT : You need to have administrator privileges on the 
local machine, so log on as administrator if your account doesnl 
have these. 

2. Open a Command Prompt and cd into the directory into which you 
installed WinVNC. eg: 

I>:\> C: 

C:\> cd "XProgram Files \ORIi\VNC" 

3. Install the WinVNC sennce using the -install option. A dialog box 
will appear to indicate the success or failure of the operation. 

C:\Program Files\ORIi\VNC> winvnc -install 

Windows 95 : The WinVNC service is rK>w running and is installed 
to run whenever the system boots up into Windows 95. 

Windows NT : The WinVNC service is installed and set up to run 
whenever the machine is booted into Windows NT but IS NOT YET 
RUNNING ! You can run and stop the WinVNC service using the 
Windows control panel, or using "net start" and "net stop' 

C:\> net start winvnc 

4. if you wish to change the WinVNC settings (eg. password) when it 
is running as a service and Is therefore not visible on the taskbar, 
you must use the -settings option. 

Open a command prompt and move into the directory into which 
you installed WinVNC, as descn*bed in part 2) above. Use the 
-settings option to cause the service to display its Properties cfialog. 

C:\Program Files\ORL\VNC> winvnc -settings 

NOTE : Windows NT : The settings used by the winvnc service are 
the Default user settings and are stored per-machine, rather than 
on a per-user basis as is done when running WinVNC normally. 
Access for all users will t>e controlled by the one machine-spedfic 
password. 

NOTE : Windows 95 : If Win95 has been set to use different settings 
for each user then the settings used are those of the currently 
logged in user. If no user is logged in or Win95 is set to use the 
same settings for all users then the settings used are the Default 
user settings arKi are stored per-machtne, rather than on a 
per-user basis as is done when running WinVNC normally. (Under 
Win95, pressing Cancel on the login dialog gives access to the 



Open a command prompt and move into the directory into which 



#Open a command prompt and move i^^th< 
you installed WinVNC. 
Use the -remove option, which will aclWati 



Use the -remove option, which will acWmatically stop the service 
and then remove it, and show a dialog box to indicate the success 
or failure of the operation. 

C:\Program Files \ORI*\VNC> winvnc -remove 

NOTE : Failure to remove the service usually indicates that it was 
not installed in the first place! 
6. The full command-line options available are as follows (for version 
R19 and later). You probably woni need anything other than those 
listed above unless you're a real VNC power-userl 



-r\m Causes WinVNC to run nomnally & ignore rest of 
command-line. 

- inst:all Installs the WinVNC service and continues reading the 
command-line. 

-remove Removes the WinVNC service and continues reading 
the command-line. 

-setitings Tells a running copy of WinVNC to show its Properties 
box. 

-kill Kins a running copy of WinVNC. 

-about Tells a running copy of WinVNC to show its About box 

If no options are given then WinVNC runs normally. Multiple option 
may be given, so, for example, to upgrade from a running copy of 
WinVNC to a new one, you could use: 
WinVNC_new -remove -install 

Which will stop & remove the old copy & install the new one as a 
service, or 

WinVNC_new -kill -run 

which win stop the running copy & run the new version normally. 

WinVNC - Advanced Settings 

Extra options have been added to WinVNC for use primarily by system 
administrators, to tailor the server^ behaviour to meet their particular 
needs. The options are DWORD values which can be set in the system 
registry, and toots such as the Windows Policy Editor can be used to 
apply tfiese settings across a large number of machines. 

Versions 3.3.2 R5 and later use a more sophisticated organisation of 
these options to allow nK>re flexibinty. It also makes it rather complex, so 
we're thinking about alternative ways of doing this. WinVNC will currently 
look for settings in the following places: 



1. Local machine-specific settings . Options specified here are not 
overridable. Location: 

HKEY.LCX:AU_MACHINE\Software\ORL\WinVNC3\ 

2. Lx>cal default user settings. Location: 
HKEY_LOCAL_MACHINE\Software\ORL\WinVNC3\DefauIt 

3. Local per-user settings . These override the local default user 
settings. If there is no current user, the usemame SYSTEM will be 



. used. Location: 

HKEY_LOCAL_MACHINE\Softvvarej^|\Vy^nVNC3\ <usemame> 
4. Global per-user settings. Thes^^Ponty read if AllowProperties 
has not been set to zero (see below) Location: 
HKEY_CURRENT.USEFRSoftware\ORL\WlnVNC3 

Most options can only be specified in a subset of these places, as 
specified in each option's description below. 

Advanced Options: 
AuthRequired 

By default, all WinVNC servers will not accept incoming 
connections unless the server has had its password field set to a 
non-null value. This restriction was placed to ensure that 
misconfigured servers would not open security loopholes without 
the user realising. If a server is only to be used on a secure LAN, 
however, it may be desirable to forego such checking and allow 
machines to have a null password. Setting this registry value to 
zero will disable null-password checking by WinVNC. Local 
machine-specific setting. 

AllowLoopback 

By default, WinVNC senders disallow any vncviewer connections 
from the same machine. For testing purposes, or. potentially, when 
using multiple instances of WinVNC on Windows Terminal Server, 
this behaviour is undesirable. Setting this registry entry to 1 wOl 
cause local-loopback connections to be allowed. Setting it to zero 
will filter out such connections. Local machine-specific setting* 

AllowProperties 

If this is set to zero, the user is not allowed to view tiie properties 
dialog and hence cannot change any settings, Induding the 
password. Note that ttiis stops all global per-user settings. A valid 
password must therefore be in force before using this setting, 
generally in the local default-user setting. Local per-tiser setting. 

AllowShutdown 

If this is set to zero, tiie user Is not allowed to dose down WinVNC. 
Local per-user setting. 

AutoPor^elect 

Causes WinVNC to select the first available display number 
automatically. Con-esponds to the 'Auto' checkbox in the Properties 
dialog. Local or Global per-user setting 

CORBAConnect 

Only relevant in internal AT&T version, i-ocai or Global per-user 
setting 

DebugLevel 
DebugMode 

Run-time logging of all intemal debug messages is now supported. 
Log data may be output to a file or a console window (or the MSVC 
debugger if the program was complied with debugging active.) Two 
registry keys are used: 

DebugMode indicates which logging methods to use, 




[1 = MSVC debugger] 

2 = Output to log file \/Vinvnc.log in the WInVNC directory 
4 = Output to a console window, displayed on-screen 
Any combination of the ab»ove values may be used. e.g. 
OebugModes6 will cause output to be sent both to the WinVNC.log 
file and to the a console window on the desktop. 

DebugLevel indicates how much debug infonnatlon to present. Any 
positive Integer is valid. Zero indicates that no debugging 
information should be produced and is the default A value of 
around 10-12 will cause full debugging output to be produced. 
Local machine-specific setting. 

ConnectPriority 

By default, all WinVNC servers will disconnect any existing 
connections when an incoming, non-shared connection is 
authenticated. This behaviour is undesirable when the server 
machine is being used as a shared workstation by several users or 
when remoting a single display to multiple cHents for vewing, as in a 
classroom situation. 

ConnectPriority indicates what WinVNC should do when a 
non*shared connection is received: 

0 ss Disconnect all existing connections. 

1 = Don't disconnect any existing connections. 

2 = Refuse the new connection. 

This is a Local machine-specific setting. 
InputsEnabled 

Corresponds (inversely) to the 'Disable Remote keyboard and 
pointer* option in the Properties dialog box. Local or Global 
per-user setting 

LockSetting 

WinVNC can be made to take actions when a viewer disconnectsby 
setting this value as follows: 

0 - none 

1 - lock workstation on disconnect (not currentiy implemented) 

2 - logoff on disconnect 

Local or Global per-user setting 

Password 

Local or Global per-user setting 

PoliUnderCursor, PollForeground, PdiFuliScreen, 
OniyPoliConsole, OnlyPoilOnEvent 

These corresporxJ to the options in the Properties dialog box. Local 
or Global per-user settings 

PortNumber 

specifies the port number to be used for VNC 
Local or Global per-user setting 

SocketConnect 

This corresponds to the 'Accept Socket Connections' option in the 
orooerties dialoq box and is a Local or Global per-user setting . 



IpVNCHooks - Advanced S^||pgs 

WinVNC uses a special library, VNCHooks, to hook into the other 
running applications and retrieve notifications of areas of the screen 
being changed. The VNCHooks library uses the messages sent to 
visible Windows to decide which areas need considering for update. Not 
all applications use the same method of updating the screen, so you can 
tweak the method used by WinVNC for particular applications by editing 
the registry. All the entries listed can be found under 

HKEY_CURRENT_USERVSoftware\ORL\VNCH<x>ks\Applicatron_Prefs 

• use.GetUpdateRect 

When a window redeves a message, (WtAJPAlNT), indicating that 
it should repaint itself, it is possible to find out precisely which 
regions have changed, so that WinVNC need only scan those for 
potential updates .increasing efficiency. However, this can cause 
graphical glitches occasionally, particularly when an application 
scrolls the contents of its window, in which case only ttie revealed 
section of the window is marked as needing to be updated. If these 
glitches prove to be a problem then edit the 

<appnaiae>\use_Get:UpdateRectentry in the registry. A value of 
one indicates that this opttmisat'on will be used, while a value of 
zero indicates that it will not 

• useJTimer 

A number of Windows applications, most notably the Clock program, 
use WM_TIMER events to tngger updates to their displays, rather 
than WM_PAINT messages. By default, timer messages are not 
used to notify WinVNC of potential updates, since many programs 
use timer events for purposes other than updating the screen. As a 
result, the clock and a few other applications don't normafly update 
conBCtfy under WinVNC. The fix to this is to edit the 
<appneuae>\use_Timer entry In tiie registry, A value of one 
indicates that WM_TIMER messages will trigger WinVNC updates, 
while a value of zero indicates that they will not. 

• use.KeyPress 
Some Windows applications write characters direcHy to the screen 
when a user types into a window, rather than using WM_PAINT 
messages to cause the text to be redrawn. To fix this, WinVNC can 
scan the window every time a key is pressed, In order to catch the 
change. To set this value for a problem application, edit the 
<appname>\use_KeyPress entry in the registry. A value of one 
Indicates tiiat key presses will cause updates, while a value of zero 
indicates that they will not 

• use.tButtonllp, use_MButtonUp , use_RButtonUp, 
Some Windows applications update the display directiy in response 
to mouse dicks, without using intermediate WM.PAINT messages, 
for example. In order to catch such updates, it is necessary to 
trigger WinVNC to update the relevant window whenever the left 
mouse button is released. To set this value for a problem 
application, edit the <appname>\u8e.iiButt:onUpentry in the 
registry. A value of one indicates tftat left-button clicks will cause 
updates, while a value of zero indicates that they will not The 
same rules apply to the middle and right buttons using the 




appropriate value name. 
• use_Deferral 

"The VNCHooks library catches messages sent to windows before 
they are dealt with by the window. As a result, sendlng^uodate 

VWnVNC sending the updated area to the client before it hal 
achially been redrawn by the application! This is a ^mmoS 
problem. especiaJly on multiprocessor versions of NT so deferred 
updates are used by default Deferred updates are han^X 
postng a custom message back Into the window's oS^ nSSge 
queue rather than posting to WInVNC directly. By th^^,^^^ 
custom message is seen again by the VNCHoote HbraTthe 
message that^used It will have been handled and tS^i^te can 
then be forwarded to WinVNC without danger of being hS2 
prematurely. A few programs don't handle S,ese SrSSL^es in 

Dy editJng the <appname>\use_Def erral entry in the reaistrv A 
value of zero Indicates that they win not ^'^^.wnuea 

Running on other Win32 systems 

WlnVNCs usefulness when run as a service on this n!««!III« •# . 

Problems? 

If you have difficulties which are not covered by this document tn, 



go back to documentation 



Copyrighl 1999 - AT&T Laboratories Canfcricjge 
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MacVNC - VNC server for Macintosh 



Beta 2 -7/6/99 
Alpha 1 .1-25/1/99 
Alpha 1 -16/7/98. 



Use of the Mac server should be straightforward if you are familiar with the 
concepts behind VNC, and have a suitable VNC viewer running on 
another machine. Read 'What is VNC? ' and ' Getting Started' if you haven't 
already done so - they'll give you a good overview, despite being Unix 
and Windows-orientated. 

Note. This is a beta release. As with all VNC software, you use at your own 
riski We welcome bug fixes/ comments. 

Requirements: 

To use the Macintosh VNC server, you will need: 

• A version of MacOS greater than 7.6.1 , 

• A Power PC machine 

• Open Transport (1 .1 .3 or later). 

Quick Start 

• Drag vncPatches from the •>Extensions folder of the distribution onto 
a closed System Folder 

• Drag the VNC Controls from ->Contnol Panels onto a closed System 
Folder 

• Restart the machine 

• Run VNCServer 

• Run VNC Controls and set the password/ desktop name. Set display 
number to 0. 

^ Connect with a VNC client to <hostname>:0 or with a Java capable 
web browser to http://<hostname>:5800 

introduction 



The installation is in three parts, the patches, the server and the6ohbj>l 
L - P^?*- T^fd^atehes On a system extension called vricPatch^^isT^^^^ the 
^£j^^^^^^§^^^^ of the distributipo) Mtch dnav^g^^^^h^^^bass 
^^^^^^^^^^^W^eiVer. To install, tfi^^ ^^ : ^^^^^^^^^ ^^ 
^^r inside your S^^/S^6Mief^ 



into effect. 
The Server 

The actual work horse of the installation is the VNCServer program. Note: 
even though youVe installed the patches, no one will be able to access 
your nnachine unless the server is running as well. To automat'caliy have 

the server run at s tart up you can put It (or one of its ali ases) into the 

Startup items sub folder of your system folder. Otherwise, Just double dick 
it like any other application. 

The Control Panel 



Once the server is ninning, youll need to set the password (the default is 
none, which means the server will refuse all connections). The server 
currently supports 3 ways of setting options, via a web browser, the contro 
panel or Apple Script . The easiest and most reliable way is to use the 
control panel (called VNC Controls). Note: The server needs to be running 
(or at least have been run) the first time you use the control panel (why? ). 
Also, the control panel may pause for a few seconds (more on over toaded 
machines) whilst it communicates with the server. If the control panel is put 
into the Control Panels folder (inskie the System Folder), then it will be 
accessible by selecting the Options menu option from the server. 

The first two options determine how your screen will be described to 
clients, the desktop name is what extemai viewers will see in their title 
bars, while the display number is what theyll have to add to your host 
name for them to connect property (i.e. if you set the server running on 
machine 123.456.789.789 to have a display number of 0, then viewers can 
connect by specifying 123.456.789.789:0 or computer.room.place.com:0 as 
the host name). The display number is NOT normally the TCP/IP port 
number (see web site for further details). The password box is (surprise, 
surprise) where you should enter your desired password. Only the first 8 
characters will be used in authentteation but it is case sensitive (i.e. 
thispassword is the same as thispassXXX but not the same as THISPASS). 

Macintoshes have a key (the command key) that most other computers 
lack, which means that for an extemai client to send commarKl key events, 
some sort of key press equivalent needs to be set The four drop down 
menus specify whteh key combination will be used as command. For 
example, if you wanted your extemai cCents to get oommand-c by pressing 
left control + right alt + F3+ c you'd select "L Control". "R AIT, ■F3" and 
"None* from the four menus. Other key presses can be set via the Apple 
Script interface. 

The advanced button on the control panel takes you though to a slightly 
different set of options, which are described more fully on the panel itself. 

If the VNC server preferences file is tocked for any reason, no option 
settings will be aflowed through any of the 3 interfaces. Also the web 
interface and the Apple Script interface can be disabled by setting the 
appropriate flags on the Advanced settings page. 

, Once the Initiar spittings ha\^; ^6tTset, that's Jt^Th^^erver can be stopped 
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jr capable web browser can connect to http-^ho 



capable web browser can connect to http-^host name>:58xx (where xx is 
the display number) and wtii be sent a Java viewer that will then act as the 
VNC client. The Mac server can also accept option changes through local 
browsers accessing http://<host name>:58xx/settings.html. There is also 
way to look at the server's internal logs by looking at httpy/<host 
name>:58xx/log.html 

All the html sent out by the server needs is kept in a directory called Htm l 
which should be in the same directory as the VNCServer binary. You can 
change the k>ok of your server's settings page by changing the contents of 
this directory. RIes ending .tmpi will be put through a template parser 
befor e being se nt out, so in your customised html you can include things 
like $HOSTNAME if you want to display your current desktop narrie. See 
the included .tmpi files for examples of other variables. You can change 
where the server k>oks for its html by changing the HtmlDirectory line In 
VNC Sender preferences (found in the <startup disk>:System 
FoldenPreferences) or you can include the html/ tmpI files as TEXT 
resources tnskie the VNCServer binary. The names of the resources 
should be the same as the names of the files. Resources are searched 
before the Html directory. 

The web interface can be disabled by removing the Html directory or 
clearing the "Use Http Options" flag on the Advanced screen of the VNC 
control panel. 

The Apple Script interface 

The server can be controlled by Apple Scripts which can be easily written 
with the Script Editor which comes with every installation of the Mac OS. A 
sample program is shown below. 

— example for coznmxmlcating with a VNC server 
tell application "VNCServer* 

— set tlie options to sensible things 
set password to "password* 

set display number to 34 

set desktop name to "Bob's Con^uter" 

set cmd equivalent to "ffeS ffe9 0000 0000" 

— The following is a very esoteric option described 
set mouse id to "03045ef2" 

— get a table of function use {very uninteresting) 
get stats 

— Clear the previous st:atistics 
set stats to 0 



end tell 




consisting of four space deliminated, u^lSfixed, four digit hexadecimal 
numbers (got that?). Seeing as most users are not going to know (or care) 
what an X key sym is, the control panel includes a way of easily setting 
this combination via four drop down menus. People who are quite happy 
with a Ctrl/ alt/ shift etc. style key press can use the control panel while 
others can set what evdr key press they like via this Apple Script 
command. 



mouse id 

The mouse id option is for people with more than one mouse on their bus 
who don*t want to use the first one as the captured pointing device (for 
-whateverHreason). By default, the first pointing deviee-enoeuntered by the 
CursorDevice manager is the one that is controlled by clients. However, if 
you want the clients to control the second one, then youVe going to have 
to find out the device ID of the second mouse and pass it to the the server 
via the mouse id command. The parameter is a string containing the device 
ID in hexadecimal with no leading characters. Very very few people are 
going to need this. 

Question Index 

How Do I ... 

... stop other users changing the settings once I have set them? 
... use my command key from other machines? 
... customise my html pages? 
^ ... paste into my Mac from a remote connection? 

..^ communteate my feedback to AT&T l.aboratories Cambridge? 

Why ... 

... does my machine keep crashing? 
... doesn't the Server Options., menu item work? 
... wont the control panel run unless the server has been run at least 
once before? 

How Do i.... 

Q. ... stop other users changing the settings once I have set them? 

A. Make the preferences file (which is called VNC Server preferences nd 
should t>e In the Preferences file inside the System Fokler) read only. 

Q. ^ use my command key from other machines? 

A. The modifiers ttiat correspond to command can be set via the settings 
page or via Apple Script. The default is Left Alt arKi Left Control. So L Alt+ 
L Control + c is the same as command + c. Note: The command key is the 
one next to the space bar with a propeller symbol or an Apple symtx)! on 
it 

Up to four modifiers can be chosen and are descrit>ed by thier X keysym 
values. See keysyrns.h In the sourpe distnljution for more details of X 
Jceysyrtei^eid e^^t^fl^jfi^^ down menus..tQ,pdl^(^.frorn^r^^ 

num6^r^^<aj?^iito^ rnodiifers to thes^^l^l^ plj^^' 



The modifiers can be set from AppleScript like this: 



tell application 'VNCserver* 
set cmd equivalent to "ffe3 ffe9 0000 0000" 
end tell 



The string is four 4 digit hexaded maJ n umbers dftscribing the modifierB 
requested. (ffe3 ffe9 correspond to the default L AK -f L Control). 

Note: Setting the modifiers to anything strange will produce "Current 
Modifiers: unknown" on ttie s ettings page. Do not panic. Th is just means 
that the server doesnl knovThow to describe the keysyms you Ve given i' 
They will still work, iTs just the server doesnt have name for them. 



Q. ^ customise my settings/ logs / initial page? 

A. The HTTP server look at the following places for HTTP files: 

• The directory specified in the Html directory line in the preference 
file. (Default is the directory called Html in the same directory as the 
server) 

• Resources of type TEXT inside VNCServer 

• Resources of type ' WWW inside VNCServer (There's a space 
before the first W in ' WWW^ 

• Resources of type 'JAVA inside VNCServer 

You can therfore override the intemal html files by putting new files In the 
Html directory. 

Also, the server will transform certain filenames under cetain conditior 



Condition... 

Connection is local and the 
server unlocked 

Connection is not local and 
the server is unlocked 

Server is locked 

Server is running property 

Server is not running 
properly 

Status info Is avall€dble. 
Status info is not availble 
Status info is available. 
Status info is not availble 



Maps ... to ... 

settings.html settings.tmpl 

settings.html localonly.tmpi 



settings.html 

index.htmi or 
/ 

index.html or 

/ 

log.html 
log.html 
log<X>.html 
log<X>.html 



noserver.html 
javastarttmpi 

noserver.html 

iog.tmpi 
noserverhtml 
singleJog.tmpl 
single.tog.tmpi 



The <X> in the last two files is an asdi character from 0 onwards tliat 
describes vvhicb log riurnber you want 



LogHdiSrthej 



npuipg. log 1 is the http log,iog 2 isa 




Most of the html files served are passed 
being sent to the client. The template pai 
useful information: 



irs^nra 



h a template parser before 
ranslates some tokens into 



Token ... 

$SETTINGS_UNK 
$HOST 

$WIDTH,$APPLETWIDTH 
$HeiGHT.$APPLETHElGHT 

$LOG<X> 

$MAiNPAGE 

$PORT 

SDESKTOP 
$D1SPLAY 

$MODIFIERS 
STHELOG 



Expands to... 

<A href=<host>/settings.html>Settings</A> if 
t he connectfo n is local and the server 
unlocked. Nothiong othenvise. 

The ip address of the host. 

The width of the screen 

' Tfie height of fhe screen 

The specified log. <X> is an ascii character 
starting at 0 which specifys the log 

A fully formed URL to the index page 

The port number for vnc connections 
(normally 5900) 

The user specified narrie of the desktop 

The display number. Normally 0 

English description of the modifers that 
correspond to the command key 

A log. This token only works In 
singleJog.html, which is only used when the 
user requests log<X>.htmI. See above for 
what the <X> means. 



Settings can be changed by sending a POST event to the server, via a an 
HTML fomn. 

The labels in the POST correspond to various variables: 



Label... 
PASS 

PAS2 

DISP 
DESK 

Key1 ,Key2,Key3,Key4 



Variable . 
The password 

The password again. It will be set if both of these 
are the same 

Display number 

Desktop name 

The command key modifiers. 



In response to a POST event (usually sent from the settings page) the 
server returns changed.tmpi unless the password was incorrectly set in 
which case passwrong.tmpl is sent. 



Q. ^. paste into my Mac from another machine? 



A. The short answer is "You can't". The kjnger answer Is "You cant 
because^f tf).6isngh odd way the Mac handles di;?bQaal^"^This prpbl^^ 



Q. ... communicate with the develoi 



A. We run a VNC mailing list ain that has a pretty large membership fist and 
IS read by all the VNC developers (not just the Mac one), so any questions 
you have can probably be answered by posting to this list. To join the list 
go here. Note that asking questions which are answered in this document 
or in the FAQ is a Bad Idea. 



Why?.. 

Q- does my machine keep crashing? 

A. VNCServer, In its fastest mode, breaks a general guideline In that it 
patches ShowCursor (which has to be Intenrupt time safe) with some code 
that isnt intemjpt safe. This may sometimes cause bad things to happen. If 
this is happening to you, you can switch to an intenxipt-safe version of 
ShowCursor by changing the "Use Error prone updates" flag in the security 
resource. See above for details. The downside is that updates that happen 
when the mouse button is down (like drags and menu operation) may not 
work so well. 

As mentioned above, there are also some known problems with the hextile 
encoding. You should find that the server is nK>re reliable if you switch this 
off. 

Q. ... doesnt the File/Options(HTTP).. menu item work? 

A. The server options are set using a web browser via an HTTP 
conrtection. If your machine isnt set up for this already, you need Internet 
Config to make this work. From the IC faq: 

Each new release of Internet Config Is posted to MacGifts and is 
therefore available Info-Mac and UMich (and their mirror sites). It is 
also available from any site that holds Peter Lewis' software, namely 
AOL. AMUG, PopCo, Australia. Japan, and Switzerland. 

Internet Config Is also available as a NewsWatcher helper and on the 
TidBITS site. 

Rnally, all sorts of IC related material. Including the latest version of 
the IC software, is available from the IC home sites in Australia and 
the USA. 



Q: ... wont the control panel run unless the server has been run at 
least once before? 



A: The reason for this is that the panel either communicates directly with 
the server (through Apple Script ) or alters Its preferences file. If the server 
has never been run before, there will be no preferences file on the system 
and the panel wont be able to do anything. 



Any cornmehte regarding this program shouM be directed to the VNC 

.mitQn^;OsU-* 
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rfbcounter 

A real^sim'ple VNC server. 



rfbcounter 




We thought we'd release the source code of this just to show that a VNC 
server doesn't have to be big and complicated, and that you can display 
things other than desktops! 

Rfbcounter creates and updates a simple numeric counter It does so by 
generating raw VNC protocol to produce the digits, and does not have a 
f ramebuffer of Its own. 

The name comes from the fact that the VNC protocol is sometimes 
referred to as the RFB protocol. RFB stands for 'Remote Framebuffer'. 

The source code for rfbcounter can be found, tarred and gripped, here. 
It is a single C file with a couple of headers, and should compile easily 
on Unux, and with very little effort on Win32 and other flavours of Unix. 

Usage: 

rfbcounter [-clock! display-number width [fgj [bg] 

eg. if you run 

rfbcounter 5 300 

you can then connect a VNC viewer to display 5 on that machine and 
you1l get a counter 500 pixels wide. The fg & bg arguments are single 
byte values specifying foreground and background colours in BGR233. 
By prefixing with a zero, you can use octal to simplify color selection, for 
example 0007 01 00 Is bright red on a dark blue background. If you 
specify the -dock optfon. rfi^counter will display the cunrent time instead 
of a free-running counter, and update it once a minute. 

Note: rfbcounter does not do any pixel translation. • Ypur.viewer *must* 
cope with 8-bit bgr233 fdmriat for this to . . Jivorfe On uiibc. use the -bgr233 
■ rtfon to vncviewer..:-.gv.g ^^^^-f' ~ ---- - ^- - ^ - 

Tis is not an examole of obod VNG" 




# • 
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VNCviewer forX 

Run it and give the displayaTs an al^iOiTienir " " 

vncviewer snoopy: 2 

where 'snoop/ is the name of the machine, and '2' is the display 
number of the VNC server on that machine. The -h argument will show 
you the other options. The important ones are as follows: 

-shared 

When you make a connection to a VNC sender, all other 
existing connections are nomially closed. This option 
requests that they be left open, allowing you to share the 
desktop with someone already using it. 

-display Xdisplay 

This allows you to spedfy the X display on which the 
^ VNCviewer window should appear. 

-^asswd password-file 

If you are on a filesystem which gives you access to the 
password file used by the server, you can specify it here to 
avoid typing it in. 

-viewonly 

Specifies that no keyt>oard or mouse events should l>e sent to 
the server. Useful if you want to view a desktop without 
interfering; often needs to be combined with . -shared 

-geometry geometry 

Standard X position and sizing specification. . 

-bgr233 

This tells the VNC server to send pixels which are only 8 bits 
deep. If your server desktop is deeper than this then it will 
translate the pbcels t>efore sending them. Less data will 
generally be sent over then network, v^ich can be a big 
advantage on slow links, but the sender may have to work a 
bit harder, and you may get some colour mismatches. This Is 
the 8-bit true colour pixel format used by the java dient, with 
the most significant two bits of each byte representing the 
blue component, the next three bits representing green and 
the least significant three representing red, hence 'bgr233*. 
-raw, -copyrect, -rre, -corre, -hextile, -nocopyrect, 
-norre, -nocorre, -nohextile 

These optioris affect \yhich encodings vncviewer tells the 
VNC sender jt^paiT -Normally it requests CopyRect, 

He)ATe j^Bgl^D that order. The pp^jns after*is 

iL^JtvS: -a^^^^^^g^^^ spedfyirig 0^t^^^^ 
.^r<ftK>: ^' f^^^^^^^^^^^^i^ before anv of \hi 



-depth d 

This is only useful on a (real) X sen/er which supports 
multiple depths. On such a display vncviewer will try to find 
a Visual of the given depth. If successful this means that the 
appropriate pixel fonmal will be requested from the VNC 
server. You cannot use this to force a particular depth from 
the VNC server. The only option which does this is -bgr233. 

-truecolo\ir 

vncviewer will try to find an X visual of the TmeColor class. 

-owncmap 

vncviewer will try to find a PseudoColor visual and use its 
own Colormap. _ 

-period ms 

This tells vncviewer not to request incremental framebuffer 
updates more often than the given period In milliseconds. If 
you have a very fast client and server, you can use this 
option to limit the rate of updates - this can result in using 
less networic bandwidth. 

-wmdecoration Wxh 

Nonnally the viewer window will be the same size as the 
desktop you're connecting to, plus any decorations added by 
your local window manager. If your local screen is too sn^t 
to display this then it will make the window as big as it can 
while still allowing room for decorations, and display 
scrollbars. This option allows you to specify how big your 
window manager's decorations are, so that it can make this 
decision correctly. In particular, some people run v^out a 
local window manager, and specifying -wmdeooration 0x0 
will then allow a completely full-screen window. 

-rawdelay ms 

This is useful tor checking exactly which parts of the screen • 
are being updated. For each update rectangle vncviewer 
puts up a black rectangle for the given time before putting up 
the pixel data. This only highlights pixel data sent using the 
raw encoding. 

-copyrectdelay ms 

This wori<s as with -rawdelay above, but highlights the areas 
copied using the copyrect encoding. 

-debug 

This prints out all the data received from the VNC server In 
both hex and ASCII. 
-list:en 

This is used for AT&Ts internal version of VNC. It causes 
vncviewer to listen on port 5500+<display-numt)er> for 
reverse connections from a VNC server. See 
httpy/www.uk.research.att.com/vnc/intemalver5k)n.html 

'go back to documentation 



For comments. fe^ct>aQk,.6tc, please see the 'Keeping in touch' pag& 
X5obvTiaht:l999 - AT&T Latxsratories Cambrkige 
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VNCviewer for Windows 

'on can-run the wmdowsT vncviewer from the'commandlnifforirom'a 
shortcut and it will prompt you for a display: 

vncviewer 

You can specify a display on the command line: 

vncviewer snoopy: 2 

And you can run It with -h to get a list of other Important options. The 
full list is below. These can all take either - or / as the switch 
character. Most of the options can also be set from the 'Options...' 
dialog box which is available from the initial connection prompt before 
connecting, and some from the system menu by'Sicking the VNC logo 
in the top-left comer of the window after connection, and selecting 
"Connection options...'. 

The system menu also allows you to see some information about the 
connection, start new connections, and send a Ctrl-Alt-Del to a 
remote machine. This will only have an effect if the renrK>te server is 
able to interpret it. currentiy only true for WinVNC running as a service 
under NT 4. 

Keystrokes such as Ctri-Esc and Alt-Tab may be Interpreted at tiie 
local (viewer) machine. If you want to send them to the remote 
machine, you can use the options on the viewer menu to send 
individual Ctrl-down, Ctrt-up. Alt-down and Alt-up keystrokes. For 
example, to type Ctrt-Esc on the remote machine, send Ctrl-down 
using the menu, press Esc, and then send Ctil-up (or just tap the Ctrl 
key) to release the Ctrl key at the remote end. 

Command line options: 

-shared 

When you make a connection to a VNC server, all other existing 
connections are normally closed. This option requests that they 
be left open, allowing you to share the desktop with someone 
already using it. 
-Sbit 

The viewer will normally accept whatever pixel format the server 
offers and dd the translation locally. Thls.fofces It to request 
8-blt tnie-<x>lour ^BpR233) from, fee server^^ich will reduce 
networic^"^- " "--^-^ ™' ^ 




command line or in the dialog bo> 
- s wapmou s e 

This option was more commonly used before the 3-button 
emulation was available. Normally the PC buttons 
left-middle-right are mapped on to X buttons 1^,3. This switch 
causes them to be mapped onto buttons 1 ,3,2, which may be 
more useful for two-button users who only have left-right, 
because they will then get button s 1 & 2 inst ead of 1 & 3. 
If combined with 3-button emutation, this also causes the middle 
button to emulate button 3 instead of button 2. This may be useful 
if you use button 2 more. 

-emulates timeout 

When using 3-i>ufton emuratidn, BotK mouse buttons must be 
pressed within a certain period for them to be registered as a 
single middle-click instead of sepsu^te left and right clicks. This 
option allows that time period to be specified in msec. The default 
is 100. 

*- wnilateS f uz z 

When using 3-button emulation, both mouse.buttons must be 
pressed within a certain distance of each other for them to be 
registered as a single mkidle-cfick. This option allows that 
distance to be specified in pixels. The defeiult is 4. 

-fullscreen 

This causes connections to start in full-screen mode by default 
See t>eIow for more details. 

-dlsablec 1 ipboard 

Clipboard changes caused by cutting or copying at either the 
viewer or server end are normally transmitted to the other end. 
This option disables clipboard transfers. 

-bel Idei coni f y 

VNC allows for the transmission of a 'bell* character, causing a 
beep at the viewer if it has sound facilities. You can set the 
sound to be used for the bell under the VNCvlewer section of 
'Sounds' In the Control Panel. Often a beep will happen 
because you are being notified of something such as email 
arriving or compilation finishing. This switch causes a minimized 
vncviewer to l>e un-minimlzed when a bell character is received. 

-listen 

In the Internal version of VNC used at 
AT&T Latx>ratories Cambridge, the 
server can initiate connections to the 
clients under CORBA control. This switch puts vncviewer into 
listening mode where it can accept these connections, t>ut It also 
has a useful side-effect which may be of Interest to those outskie 
AT&T using the public version. A listening vncviewer does not 
pop up a connection dialog, but instead Installs itself in the 
system tray. From there you can easily start up new connections 
and can set default options to be used for them during this 
instance of the program. RECENT NEWS! The latest ver5k>ns of 
Win VNC can initiate the connectk>n to a viewer using the 'Add 
New Clidnf menu option. For this to work, the viewer must be in 
listeriirigrribd^.'- ' ' - . 

iemA and not very tSlf 
sfittv^ selected for an ' 






specify it on the command line to cause vncviewer to attempt to 
load ttiis in the future. Note that vncviewer does not currently 
support 'dead keys*, and that the differences between language 
and keyboard are confusing and the way they are handled is 
different in Windows 95 and NT. But this may help a bit 

-logfile filename 

VNCviewer (R6 and later) has a logging mechanism which can 
save some debugging information to a file or display it on a 
console. This option specifies the name of a file to which a log 
will be written. 

-log level n 

This option controls the amount of logging information sent to the 
log file. The default is zero, and higher values (up to about 12) 
will provide more detail, 
-console 

In addition to, or instead of. logging to a file, this option will 
cause the debugging infonnation to t>e sent to a console window, 
-viewonly 

In View-only mode, no nnouse or keyboard events will be sent 
back to the server. This is useful for teaching sessions or other 
situations where you want to observe but dont want to interfere, 
-restricted 

In restricted mode, most of the items are removed from the menu, 
so that the user cannot, for example, send a Ctrl-Alt-Del to the 
remote end. 

Full-screen mode 

Vncviewer can now be switched into a fullscreen mode. This is 
particulariy useful when connecting to a remote screen which is the 
same size as your kx:al one. If the remote screen is bigger, you wont 
get any scrollbars, but you can scroll by bumping the mouse against 
the edge of the screen. 

To leave fullscreen mode you must disable it from the menu, but the 
menu is no longer visible! So you have to bring the taskbar to the front 
by typing Ctrl-Esc Esc. and tiien right-dick on the vncviewer feon. 
A dialog t>ox will appear when you select fullscreen mode to remind 
you of this; if, after a while you get annoyed with the dialog box, you 
can disable it by creating a DWORD registry value named 

HKEY_CURRENT_ySER\Software\ORI-\ 
VNCviewer\Settings\SklpFullScreenProi)npt 

and setting it to 1 . A simpler method will be in a future version! 

You can cause new connections to start in fullscreen mode using the 
-fullscreen command-line option. 

See also * What^ new in the Windows VNC package? 

^^go back to documentation 



For comments, feedback, etc. please see the 'Keeping in touch' paga 
Copyright 1999 - AT&T Laboratories Cambridge 
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VNCviewer for Java 

Because Java applets can only make connections back to the 
machine from which they were served, each of the VNC servers 
actually incorporates a small web server. This runs on port 58xx, 
where xx is the display number, and will only serve the Java applet 
classes and an HTML page whteh contains them. 

This means that you should be able to point any Java-capable 
browser at, for example: 

http : //snoopy : 5802/ 

and you should, after a short pause, be able to connect to your VNC 
session. 

If you are using the X-based VNC server, you may need to specify 
the directory which contains the class files in the vncserver script. 
The Win32 server has the classes embedded in the server itself. 

Java implementations seem to vary wklely both in how fast they can 
read from the network and how fast they can draw to the screen. If s 
worth using the Options dialog to experiment with different encoding 
schemes for any given network and browser. 

Running as an application 

You can run the viewer outside a browser using, for example': 

java vncvievrer HOST snoopy PORT 5902 

Note that you need to specify the actual VNC port number and not 
the display number or the HTTP port number here! The predse 
command line will depend on your particular Java Installation. 



'go back to documentation 



For comments, feedback* etc, please see the ' Keeping in toucti * paga 
Copyright 1 999 - AT&T Laboratories Cambridge 
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VNC Viewer for Macintosh 

Beta 2 -7/6/99 
Beta1 -16/7/98. 



Note. This is a beta release. As with ail VNC software, you use at 
your own risk! We welcome bugfixes/ comments. 

Requirements: 

To use the Macintosh VNCviewer, you will need: 

• MacOS 7.1 or greater, 

• the Threads Manager, 

• and Open Transport (1 .1 .1 or later) or MacTCP, though OT will 
wortc much t>etter« 

Introduction: 



Use of the Mac viewer should l>e straightforward if you are familiar 
with the concepts behind VNC, and have a suitable VNC server 
running on another machine. Read 'What is VNC? ' and 'Getting 
Started* on the VNC web site if you havent already done so - the/11 
give you a good overview, despite being Unbc and 
Windows-orientated. 

On starting tiie program, you are presented with a dialog box 
requesting the server name and display number. Type, eg. 
'snoopy:0\ or select a recent connection from the pull-dovyn list. 
You can type a dotted IP address in place of the name, eg: 
'192.168.1.3:0*. Note the display number is NOT normally the TCP/IP 
port number. You can also pop up a list of options, the important 
ones are: 



e Share desktop 
When you make a connection to a VNC server, all other 
existing connections are normally closed. This option requests 
that they be left open, allowing you to share the desktop with 
someone already using it 
e Allow only e-bit encoding 
This forces the viewer to request simple 8-blt true-poiour 
(BGR233) from the server regarcfless of loca l or ^J igg^f Py?*-"- 
■ ' " !;^d^ich can reduce ne toworic ^i^trafl " " 



26nlv mode, no inbl 





^ Scale desktop to window 
This scales the remote display to fit the local window, 
bit rough at present, but may be useful in certain 
circumstances. 



This is a 



If the connection is successful, you will be asked for your password, 
after which the remote desktop should appear. The RIe.. menu will 
allow y ou to start n ew sessions. The Connections menu lists open 
connections, along with icons representing their current status. See 
the 'Symbol Reference' option on the Apple menu for a description of 
these toons. 



Mouse Buttons (new for Beta 2) 

As the Mac mouse (usually) only has one button, some mechanism 
is needed to transmit left and middle combinations. Pressing 
command + n will toggle the use of button n. The current status of the 
button toggles is shown on the title bar of each connection. Initially 
the only toggle set is button 1 . This means when the mouse Is 
clicked a button 1 click event is sent, if you wanted to send a button 
2 dick you would turn off button 1 (via command + 1) then tum on 
button 2 (via command + 2) then dick the mouse. To retum to normal 
(button 1) use you'd need to untoggle button 2 (command + 2) and 
retoggle button 1. In this way all 8 combinations t>^3 button 
superpositions can be sent. Admittedly this is a bit long winded if you 
only want to send a button 3 click (as you woukl for pasting in Unix) 
so command + 4 and command + 5 are set to send a single dick for 
buttons 2 and 3 respectivty. 



So, to summarise, 

Command + 1 
Commnad + 2 
Command + 3 
Command + 4 
Command + 5 



Toggle use of button 1 
Toggle use of button 2 
Toggle use of button 3 
Send single button 2 click 
Send single button 3 dick 



Other modifier keys will work as nomiial so contol shift or att dragging 
can be done with any combination of mouse buttons. 

Other features: 

Keeping your finger on the Propeller key (sometimes called the 
Command key) when starting off brings up the extra preferences box. 

• Enable Logging - will trigger the production of log files 

• Kill Preferences • Delete the preferences file and prevent this 
session's preferences being recorded. The only thing currentiy 
stored in the preferences file is the list of recent connections. 



Known Issues: 
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VNCviewer for Windows CE 2.x 




Now you can view X Windows applications on your PDA! 

The VNC viewer for Windows CE Is based heavily on the Win32 
It requires Windows CE 2.0 or later. 



viewer. 



To install, make sure that TCP/IP is working correctly on your WinCE 
machine (try browsing the web), and we suggest you set the 
communications link to the fastest speed it can manage. Try connecting to 
the smallest desktop you can, initially. If you're viewing a PC or Mac, 
set the server's.screen to 640x480 or so and 256 colours. If you're 
connecting to an Xvnc server, then you can of course create a desktop 
of any size you like. Larger screens will work - IVe viewed a 
1280x1024x24 screen here, but the initial screen download takes quite a 
while, and in this version a copy of the entire remote screen is kept in the 
PDA's memory, so you'll need plenty of RAM free! 

Copy the appropriate vncview.exe binary onto the PDA and run it. If you 
have used the Windows viewer the dialogs and menus should look very 
familiar. You might want to use the Options button in the Connection 
dialog to request 8-bit pixels only. You can set this from the command 
line, so I suggest you create a shortcut to the vncview executable and 
include the '-8bit' option in the target command line. 
Most of the command-line arguments and options are taken directly from 
the Win32 viewer, and you should look at the Windows viewer 
documentation for more details, but there are a couple of CE-specific 
options: 




These options allow you to specifyuTe layout to be used 
-slow 

We have recently improved the speed dramatfcally by writing 
d'trectiy to a DIB instead of using CPs very slow GDI calls. If this 
causes problems, or if you just want to see what it used to be like, 
you can try this switch! 

The Windows CE viewer does not operate in full-screen or listening 
mode. There is no console-mode oeougging, and some of the other 
Win32 viewer options are not implemented. 




This is certainly the smallest X terminal IVe ever^sed! 

^gobaclcto documentation 



For comments, feedback, etc, please see the 'Keeping in touch ' paga 
Copyright-1999— AT&T Lai^oratories Cambridge 




The VNC protocol 



^^h^m^^ . ^' i!^ ^'gL 



The VNC system is based on the concept of a remote framebuff er or 
RFB. We therefore often refer to the protocol underlying VNC as 
the RFB protocol . 



The protocol specification (Acrobat format) 

The header file rfbproto.h which is used by the system.(Acrobat 

format) 



'go back to documentation 



For comments, feedt)ack» etc, please see the ' Keeping in touch * page 
Copyright 1999 - AT&T Laboratories Cambridge 



The RFB Protocol 



Tristan Richardson 
Kenneth R. Wood 
ORL 

■ "CambTtdge 

Version 3.3 
January 1998 

Revised J6 July 1998 



1 Introduction 

RFB (^remote framebuffer'*) is a simple protocol for remote access to graphical user 
interfaces. Because it woiks at tte fcamebufFer level it is applicable to all windowing 
systems and applications* including XI i, Windows 3.1/95yNT and Macintosh. 

The remote endpoint where the user sits (Le. the display plus keyboard and/or pointer) is 
called the RFB client The endpoint where changes to the fiamebuffer originate (Le. the 
windowing system and applications) is known as the RFB serven 



RFB Server RFB Client 




RFB is truly a *'thin client* * protocol The emphasis in the design of the RFB protocol is 
to make very few requirements of the clienL In this way, clients can rim on the widest 
range of hardware, and the task of implementing a client is made as simple as possible. 
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The protocol also makes the client stateless. If a client disconnects from a given server 
and subsequently reconnects to that same server, the state of the user interface is pre- 
served. Furthermore, a different client endpoint can be used to connect to the same RFB 
server: At the new endpoint, the user will see exactly the same graphical user interface 
as at the original endpoint In effect, th e interface to the user's applications becomes 
completely mobile. Wherever suitable network cormectivity exists* the user can access 
their own personal applications, and the state of these applications is preserved between 
accesses from different locations. This provides tlie user with a familiar, unifwrn view 
of the computing infrasmicture wherever they go . 

2 Display Protocol 

The display side of the protocol is based around a single graphics prinuti ve: "put a rect- 
angle of pixel data at a given x,y position **. At first glance this might seem an inefficient 
way of drawing many user interface components. However, allowing various different 
encodings for the pixel data gives us a large degree of flexibility in how to trade off vari- 
otis parameters such as network bandwiddi, client drawing speed and server processing 
spee± 

A sequence of these rectangles makes a fhmtebteffer update (or simply update). An 
update represents aTShJOige from one valid framebuffer state to another, so in some ways 
is similar to a frame of video. The rectangles in an update are usually disjoint but this 
is not necessarily die case. 

The update protocol is demand-driven by the client. That is, an update is only sent from 
the server to the client in^response to an explicit request from the client. This gives the 
protocol an adaptive quality. The slower the cUent and the network are, the lower tibe 
rate of updates becomes. With typical applications, changes to the same area of the 
framebuffer tend to happen soon after one another. With a slow client and/or network, 
transient states of the framebuffer can be ignored, resulting in less network traffic and 
less drawing for the client 

3 Input Protocol 

The input side of the protocol is based on a standard workstation model of a keyboard 
and multi-button pointing device. Input events are simply sent to the server by the client 
whenever the user presses a key or pointer button, or whenever the pointing deface is 
moved. These input events can also be synthesised from otiier non-standard I/O de- 
vices. For exaniple, a p^i-based handwriting recognition engine might generate key* 
board events. 

4 Representation of pixel data 



Initial interaction between the RFB client and server involves a negotiation of the>br- 
mat and encoding with which pixel data will be sent This negotiation has been de- 
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signed to make the job of the client as easy as possible. The bottom line is that the 
server must always be able to supply pixel data in the form the client wants. However 
if the client is able to cope equally with several different fonnats or encodings, it may 
choose one which js_easier for the serv er to produce. 

FlxeXformat lefeis to the representation of individual colours by pixel values. Ibe mosT 
common pixel formats are 24-bit or 16-bit •'true colour**, where bit-fieids within the 
pixel value translate directly to red, green and blue intensities, and 8-bit ^colour map*' 
where an ai^trary- mappingxan bejiscidJSLiranslme.firo pixel values to the R GB in- 
tensities. 

Encoding refers to how a rectangle of pixel data will be sent on the wire. Every rectan- 
gle of pixel data is prefixed by a header giving the X« Y position of the rectangle on the 
screen, the width and height of the rectangle, and an encoding type whidi specifies the 
encoding of the pixel data. The data itself then follows using the specified encoding. 

The protocol can be extended by adding new encoding types. The encoding types de- 
fined at present are raw encoding, copy rectangle encoding, RRE (rise-and-nm-length) 
encoding, CoRRE ( Compad RRE) encoding and hextile encoding. In practice we nor- 
mally use only the hextile and copy rectangle encodings since they provide die best 
compression for typical desktops. Other examples of possible encodings include JPEG 
for stillimages and MPEG for ef&cient transmission of moving images. 

4.1 Saw encoding 

The simplest encoding type is raw pixel data. In this case the data consists of n pixel 
values where /i is die width times the height of the rectangle. The values simply rep- 
resent each pixel in left-to-right scanline order. All RFB clients must be able to cope 
with pixel data in this raw encoding, and RFB servers should only produce raw encod- 
ing unless the client specifically asks for some other encoding type. 

4*2 Copy Rectangle encoding 

The copy rectangle encoding is a very simple and efficient encoding whii^ can be used 
when the client.already has the same pixel data elsewhere in its fiamebuffei: The en- 
coding on the wire sinqvly consists of an X, Y coordinate. This gives a position in the 
firamebuffer from which the client can copy the rectangle of pixel data. Ihis can be osed 
in a variety of situations, the most obvious of which are when the user moves a window 
across the screen, and when the contents of a window are scrolled. A less obvious use 
is for optimising drawing of text or other repeating patterns. An intelligent server may 
be able to send a pattern explicitly only once, and knowing the previous position of the 
pattern in the firamebuffer, send subsequent occurrences of the same pattern using the 
copy rectangle encoding. 
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RRE stands for rise-and-nm-length encading^md as its name implies, it is essentially 
a two-dimensional analogue of nm-length encoding. RRE-encoded rectangles arc not 
only compressed to the same degree or better than is possible with run-length encoding 
but;^ more-iuipoi taiitly, tbey anive at the client in a form whicb canljeTCTdeied" im- 
mediately and efficiently by die simplest of graphics engines. Thus, RRE is aimed at 
situations where compression is desired but the RFB client is insufficiently powerful to 
perform any decompression fast enou^ to maintain interactive performance. 

TBe basic idea behincf KRE is the partitioning of a'rectahgle'of pixel data into recfangu- 
lar subrcgions (subiectangles) each of which consists of pixeb of a single value and die 
union of which cotapxiscs the original rectangular region. The near-optimal partition 
of a given rectan^e into sudi solmctangles is relatively easy to compute. 

The resulting encoding on die wire consists of a ba<d;groimd pixel value, Vi (typically 
the most prevalent pixel value in die rectangle) and a count N, followed by a list of 
N subrcctangles, each of which consists of a tuple < v, x, y, tw, /i > where t;.{^ Vi) 
is the pix^ vahie» {x, y) are the coordinates of the subrectangle relative to the top-left 
comer of the rectan^e, and (w, h) are the width and height of the subrectangle. The 
client can render die original rectangle by drawing a filled rectangle of the background 
pixel value and then drawing a filled rectangle corresponding to each subrectangle. 

4 A CoKRE encoding 

CoRRE is a variant ^ RRE, where we guarantee that the largest rectangle sent is no 
more than 255x255 pixels.* A server which wants to send a rectangle larger than this 
simply splits it up and sends several smaller RFB rectangles. Within each of these 
smaller rectangles, a single byte can thai be used to represent the dimensions of the 
subrectangles. For a typical desktop, this results in better compression than RRE. In 
fact, the best compression is achieved when we limit die rectangle size even more - 
current implementations use a maximum of 48x48. This is because rectangles which 
do not encode well (typically diose containing image data) are sent as raw, while the 
ones which do encode well are sent as CoRRE. The smaller the marimnm rectangle 
size, the finer the granularity of this decision. With RRE, the whole original rectangle 
must either be sent as RRE. or the whole diing sent as raw. However, since diere is a 
certain overhead incurred by each RFB rectangle, inaldng die maximum rectangle size 
too small (and thus increasing the number of RFB rectangles), results in worse com- 
pression. 

4.5 Hextile encoding 

Hextile is a variation on the CoRRE idea. Rectangles are split up into 16x16 tiles, al- 
lowing the dimensions of die subrectangles to be specified in 4 bits each, 1 6 bits in total. 
Unlike CoRRE, tiles are not top-level RFB rectangles. When splitting the original rect- 
angle into tiles this is done in a predetermined way. This means that the position and 
size of each tile do not have to be explicitiy specified - the encoded contents of the tiles 
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simply follow one another in the predetermined order. The ordering of tiles that we xise 
is starting at the top left going in ieft-to-right, top^to-bottom order. If the width of the 
whole rectangle is not an exact multiple of 16 then the width of the last tile in each row 
will be correspondingly smaller. Similarly if the height of the whole rectangle is not an 
exact multiple of 16 then the height of each tile in the final tow will also be smaller. 

Each tile is either encoded as raw pixel data, or as a variation on RRE - this is specified 
by a type byte for each tile. Each tile has a background pixel value* as before. However, 
the background pixel value does not need to be explicitiy specified for a given tile if it 
' is tiie-same as the baekgn>und-of'the-pieviotts-tile<-lf -all of -tfie^ubrectangles of a tile . 
have the same pixel value, this can be specified once as a foreground pixel value for the 
whole tile. As with the backgrotmd, the foreground pixel value can be left unspecified, 
meaning it is carried over from the previous tile. 

5 Protocol Messages 

The RFB protocol can operate over any reliable transport, eidierbyte-stream or message- 
based. There are two stages to the protocol; an initial handshaking phase followed by 
the normal protocol interaction. 

The initial handshaking consists of ProtocolVersion^ Authentication^ Clientlmtialisa' 
Hon and Serverlnitialisation messages, as described below. Note that both client and 
server send a ProtocolVersion message. 

The protocol proceeds to the normal interaction stage after ih&ServerlnUialisation mes* 
sage. At this stage, the client can send whichever messages it wants, and may receive 
messages from the server as a result All these messages begin with a message-type 
byte, followed by any message-specific data. 

The following descriptions of protocol messages use the basic types CARD 8, CARDl 6, 
CARD32, INT8. INT16, INT32. These represent respectively 8, 16 and 32-bit un- 
signed integers and 8, 16 and 32-bit signed integers. All multiple byte integers (other 
than pixel values themselves) are in big endian order (most significant byte first). 
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SA Initial Handshaking Messages 
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5.1-1 ProtocolVersioii 

Handshaking begins by the server sending the client a PrvtocotVersion message. This 
lets the client know which is the latest RFB protocol version number supported by tfie 
server. The client then replies with a similar message ^ving the version number of the 
protocol which should actually be used (which may Se (Sififeient to that quoted by die 
server). 

It is intended that both clients and servers may provide some level of backwards com- 
patibilitv by this mechani_srn. Servers in particul ar sho uld attempt to pro vide backwards 
compadbility, and even forwards compatibility to some extent For example if a client 
demands version 3. 1 of the protocol a 3 .0 server can probably assnme'that by ignoring 
requests for encoding types it doesn't understand, everything will still work OK. This 
will probably not be the case for changes in the major version number. 

The ProtocolVersion message consists of 1 2 bytes interpreted as a string of ASCII char- 
acters in the format " RFB xxx . yyy \n* where xxx andyyy are the major and minor 
version numbers, padded with zeros. 



No. of bytes 



12 



Value 



■RFB OOS.OOSXn" (hex 52 46 42 20 30 30 33 2e 30 30 33 Oa) 
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5.1^ Authentication 

Once the protocol version has been decided, the server then sends a word indicating the 
authentication scheme to be used on the connection: 



No. of byte$. 


TVpe rvalue! 


Description 


4 


CARD32 

0 
1 
2 


authentication'Scheme: 
connection failed 
no authentication 
VNC authentication 



This is foUowed by data spedfic to die authentication-scheme: 



• connection failed - for some reason the connection f^ed (e.g. the server can- 
not support the desired protocol version). This is followed by a string describing 
the reason (where a stdng is specified as a length followed by that many ASCII 
diaiacters): 



No. of bytes 


Type 


[Value] 


Description 


4 

reason-length 


CARD32 
CARDS array 


reason-length 
reason-string 



The server closes the connection after sending the reason-string. 

• no authentication - no authentication is needed. The protocol continues with the 
Clientlnitialisation message. 

• VNC amhenticatiori - VNC authentication is to be used. This is followed by a 
random I6-b3rte challenge: 



No. of bytes 


Type 


[Value] 


Description 


16 


CARDS 


challenge 



The client enctypts the challenge with DES, using a password supplied by the 
user as the key, and sends the resulting 16-byte response: 



No. of bytes 


Type 


[Valuel 


Description 


16 


CARDS 


response 



The server sends a word to inform the client whether auth«itication was success- 
fuL If so, tfie protocol continues with the Clientlnitialisation message; if not the 
server closes the connection: 



No. of bytes 


Type 


[Value] 


Description 


4 


CARD32 




status'. 






0 


OK 






1 


failed 






2 


too-many 



If the server decides thaltoo^many authentication failures have occurred, it should 
not allow immediate reconnecdon by the same client 
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5,13 Clientlnitialisation 

Once the client and server are suie that they're hSippy to talk to one another, the client 
sends an initialisation message: 



No. of bytes 


Type 


[Value] 


Description 


1 


CARDS 


shared-flag 



■Shar^d'flag-A&-tion''Zim> (tiue) if the server should .try lo.shareifae desktop hy leaadng . 
other clients connected, zero (false) if it should give exclusive access to this client by 
disconnecting all other clients. 




5.1.4 Serverlnitialisation 

After receiving die Cliendnitialisation message, the server sends sl Serverlniiialistion 
message. This tells the client the width and height of the server's framebuffex. its pixel 
format and the name associated with the desktop: 



No. of bytes 


lype [Value] 


Description 


2 


CARD16 


firamebi/^er-y^idth 


2 


CARD16 


framebuffer-height 


16 


PIXEIi_FORMAT 


server-^ixel'formcU 


4 


CARD32 


name-length 


name-length 


CARD8 array 


name-string 



where PlXEIi_FORMAT is 



No. of bytes 


lype [Value] 


Description 


1 


CARD8 


bits-per-pixel 


1 


CARDS 


depth 


1 


CARDS 


big-endian-flag 


1 


CARDS 


true-colour-flag 


2 


CARD16 


red-max 


2 


CARD16 


green-max 


2 


CARD16 


blue- max 


1 


CAiUDS 


red-shift 


1 


CARDS 


green- shift 


1 


CARDS 


blue-shift 


3 




padding 



Server-pixel-ft>rmat specifies the server's natural pixel format. This pixel format will 
be used unless the client requests a different format using the SetPixelFormat message 
(section 5.Z1). 

Bits-per-pixel is the number of bits used for each pixd value on the wire. Ihis must 
be greater than or equal to the depth which is the number of useful bits in the pixel 
value. Currently bits-per-pixel must be 8, 16 or 32 — less than 8-bit pixels are not yet 
supported. Big-endian-flag is non-zero (true) if multi-byte pixels are interpreted as big 
endian. Of course diis Is meaningless for 8 bits-per-pixel. 

If true-colour-flag is non-zero (true) then the last six items specify how to extract the 
red, green and blue intensities &om the pixel value. Red-max is the DDiaximum red value 
(= 2" - 1 where n is the number of bits used for red). Note this value is always in big 
endian order. Red-shift is the number of shifts needed to get the red value in a pixel 
to the least significant bit Green-max^ green-shift and blue-max^ blue-shift are similar 
for green and blue. For example, to find the red value (between 0 and red-max) from a 
given pixel* do the following: 



Swap the pixel value according to big-endian-flag (e.g. if big-endian-flag is zero 
(false) and host byte order is big endian, then swap). 



5. 1 INITIAL HANDSHAKING MESSAGES 



11 



• Shift right by r^^/.^W^. 

• AND with re^-mor (in host byce order). ' 

Currently there is little OTKio ^ppuit fo r colour maps. Some preliminaiy work was done 
on this, but is incomplete. It was intended to be something like this: 

If true-colour-flag is zero (false) then the server uses pixel values which arc 
not direcdy comp6se31fom ffiert^ green and blue intensities; but^hich • 
serve as indices into a colour map. Entries in the colour map can be set ei- 
ther by the client using the FixColourMapEntries message (section 5.2.2) 
or by the server using the SetColourMapEmries message (section 53.2). 

Hie FixColourMapEntries message is not supported by any currently available servers, 
and colour maps are only supported at all by the X-based server. In fact, for proper 
colour map support the client probably needs to be able to speciiy particular pixel val- 
ues which the server should not use. This may be added in future versions of the pro- 
tocol, but don't hold your breath. 



12 
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5.2 Client to server messages 
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5^1 SctPixelFonnat 

Sets the format in which pixel values should be<sent Id FramebsifferUpdate messages. 
If the client does not send a SeiPlxelFormat message then the server sends pixel values 
in its natural format as specified in the ServerlnitiaUsation message (section 5.1.4). 

Currently there is little or no support for colour maps. Some preliminary work was done 
on this« but is incomplete. It was intended to be something like Otis: 

If tme-colour-flag is zero^false^Llbfia this indic ates that a "colour map" is 
to be used. The client can fix any of the entries in the colour map using the 
FixColourAfapEntries message (section 5.2.2). Any entries not fixed by 
the client may be set dynamicaUy as desired by the server using the Set- 
ColourMapEntries message (section 5.3.2). Immediately after the client 
has sent this message the colour map is empty, even if entries had previ- 
ously been fixed by the client or set by the serven 



No. of bytes 


Type 


[Value] 


Description" 


1 


CARDS 


0 


message-type 


3 






padding 


16 


PIXEL_FORMAT 




pixel-format 



where PIXEL_FORMAT is as described in section 5.1.4: 



No. of bytes 


Type [VEdue] 


Description 


1 


CARDS 


bitS'per-pixel 


1 


CARDS 


depth 


1 


CARDS 


big-endian-flag 


1 


CARDS 


Xrue-colour-flag 


2 


CARD16 


red-max 


2 


CARD16 


green-tnax 


2 


CARD16 


bhte-max 


1 


CARDS 


red-shift 


1 


CARDS 


green-shift 


1 


CARDS 


blue-shift 


3 




padding 



5.2 
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5J,J. FixCoIourMapEntries 

Currently there is little orno support forcolour maps. Some pieliminaiy wodc was done 
on this, but is incomplete. It was intended to be something like this: 

When the pixel format usesa "colour map", this message tells the serveF ' 
that the specified pixel values are mapped to the given RGB intensities. 
This means that the server may not subsequently specify RGB intensities 
for these pixel values using SetColourMapEntries messages (section 5.3 .2). 

If the client has a fixed colour map it can simply send a FixCoIourMapEn- 
tries message describing its entire colour map and the server will then trans* 
late all pixel values as ai^ropriate for the client's colour map. In this case 
the server cannot send any SetColourMapEntries messages. 

Note that despite the name, the client can, if it desires, send a FixCoIourMapEn- 
tries message at any time. This includes messages remapping the same 
pixel values to different RGB intensities. However, the only way the client 
can indicate that a pixel VBiue is no longer fixed Ls by sending another 5er* 
PixeiFormat message* whidi clears the entire colour map. 

The FixCoIourMapEntries message is not supported by any cuzroidy available 



servers. 



No. of bytes 



Type 



[Wue] 



Description 



1 
1 
2 
2 



CARD16 
CARD16 



CARDS 



1 



message-type 
padding 
first-colour 
number-of-colours 



followed by number-of-colours repetidons of the following: 



No. of bytes 



TVte 



[Wue] 



Description 



2 
2 
2 



CARD16 

CARD16 
CARD16 



red 

green 

blue 
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5.23 SetEncodings 

Sets the encoding types in which pixel data can be sent by the server. The order of the 
encoding types given in this message is a hint by the client as to its preference (the first 
encodin g specified being most preferred). The server may or may not choose to make 
use of this hinL Pixel data may always be seht innnv fflCOding^even if not specified 
explicitly here. 



No. of bytes 


Type 


(Value] 


E>escription 


I 


CARDS 


2 


message-type 


1 






padding 


2 


CARD16 




number-of-encodings 



followed by number-of-encodings repetitions of the following: 



No. of bytes 


Type [Value] 


Description 


4 


CARD32 

0 
1 

2 
4 

5 


encoding-type 

raw encoding 

copy rectangle encoding 

ERE encoding 

CoRRE encoding 

hextile encoding 



. - -"f^^.r^r- •- 
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5^4 FramebuflerUpdateRequest 

Notifies the server that the client is interested in the area of the framebuffer specified by 
x-position^y-posUion, width and height. The server usuaUy responds to a Framebuffer- 
UpdateRequest by sending a Framebt^erUpdate. Note however that a single Frame- 
' biiffertlpdaxe may be sent in reply to several FrdmebufferUpdatdR equist^: 

The server assumes that the client keeps a copy of all parts of the framebuffer in whidi 
It is interested. This means that normally the server only needs to send incremental 
updates to the client 

However, if for some reason the client has lost the contents of a particular area which it 
needs, then the client sends a FramebufferUpdateRequest with incremental set to zero 
(false). This requests that the server send the entire contents of the specified area as 
soon as possible. The area will not be updated using the copy rectangle encoding. 

If die client has not lost any contents of die area in which it is interested, then it sends a 
FramebufferUpdateRequest with incremental set to non-zero (true). If and when there 
are changes to ttie specified area of the framebuffer, the server will send a Framebuffer- 
Update, Note that there may be an indefinite period between the FramebufferUpdateRequest 
and the FramebufferUpdate. 

In the case of a fast client, the client may want to regulate the rate at which it sends 
incremental FramebufferUpdateRequest^ to avoid hogging the network. 



No. of bytes 


Type 


1 


CAKP8 


1 


CARDS 


2 


CARD16 


2 


CARD16 


2 


CARD16 


2 


CARD16 



[Value] 



Description 



message-type 

incremental 

X'position 

y-positian 

width 

height 
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Frequently Asked VNC Questions 



This isnl intended to be an introduction to VNC - have a look at the 
Started page first. 



Getting 



This fist IS being updated regularly, so, particularly if you are reading a local 
or mirrored copy, it's worth checking the original from time to tinne. The 
archives of the mailing list are also available, and they can t>e a good source 
of help - try searching them here. 

Historical Note : With the release of 3.3.2 we have moved some of the okj 
questions into the OM FAQ page because they should not apply to recent 
versions. As with wosi software, it's worth checldng to make sure youVe got 
the lastest version. 



The FAQ is divided into the foilowing sections: 



difficulties, etc 



• Problems getting started 
Installation errors, startup problems, basic communicaton 

• Problems running the programs 
Mouse problems, display issues etc. 

^ General questk>ns 
How can I make VNC faster/more secure/run on my platform? 

• Compiling the source 
Buikfing VNC for yourself. 



Problems Getting Started 
Q. Where can i get VNC? 

The latest versions of VNC and this documentation are always available from 
the AT&T Laboratories Cambridge web site at 

http://www.uk.research.attcomAmc . In addition, various add*ons, extras, and 
ports to other piatfonms can i>e found on the contribs page. 

Q. I thought this was something to do with ORL? Whafs the 
Olivetti/Oi^cle link here? 

In January 1 999, AT&T acquired ORL, tfia CMivetti R(^e2Ux:^Laboratory 
four^j. 1 2 years eariier,^^nd J^^^^'jSy^fl^^Bfe^S^^I^ • to create 
^&l>iLabbratorfes Cah " ^ - 





on it thinks it knows what type it is. V^WF/ou fill in the download form you 
specify the type of compression you would like to use. and this does not 
include .EXE. so if the thing you downloaded has that extenston, chevtge it to 
whatever you requested (usually .tgz) and then unpack the files using an 
appropriate decoder. 

Q. I unpacked the files on NT and ran SETUP.EXE but nothing 
happens. 



It appears that the 



Make sure you have NT service pack 3 installed. 
InstallShield system we use wont work without it. 

WinVNC oauses-a 'Blue Screen of Death'-on-NT! 

Again, make sure you have Service Pack 3 or later. If this happens It Is 
usually due to bugs in Service Pack 1 . Also note the Service Packs' warning 
that if you add or change components on your system you should reapply the 
service pack, ff this doesnn fix it, check for updates to your network and 
graphics drivers. VNC makes very extensive use of both your video system 
and your networic, and has a tendency to find any bugs in.either of them! 
There may well be bugs in WinVNC, but we know of people mnning it without 
problems on hundreds of machines, so please check other parts of your 
system before assuming ifs directly a WinVNC problem. 

Q. How do I set up a Windows 95/98 machine so that I can dial 
into it directly and view it using VNC? 



You aeed to install your nrxxlem from the control panel if you havent already, 
and you need to set up the dialup networidng sen/er on your server machine. 
(This is included with Win98 and NT4. On Win95 it is in the Plus! pack, but you 
need to get an update to verskwi 1 .3 or later from MIcrosoff s site. At the time of 
writing it can be found here.) You can enable the dialup server from the 
•Connections* menu of the dial-up networidng window. If it isn't there, or if 
youVe updated the dialup networidng as mentioned above, you need to install 
it using the Windows Setup section of 'Addmemove Programs' in the control 
panel. When ifs mnning and youVe dialled In, the server machine should 
have an IP address something like 192.168.55.1 as seen from the viewer - you 
can find this out by hovering over the VNC sender icon, using 'netstat -f, or 
running winipcfg. You should then be able to connect to, for example. 
192.168.55.1:0. 

I ran the vncserver program and got a 'No such file or 
directory* message. 

Vncserver is a Pert script and so the first line has to point to the place where 
Peri is installed. On Unux this will generally be /usr/bin/peri on other 
platfroms Ifs more likely to be /usr/ local/bin/perl Edit the line to point to 
the right place and it shouM woric 

Q. I ran the vncserver program and got a 'Number found where 
operator expected', 'prototype mismatch' or 'out of memory' 
message. 



': This problem should 'l^ ''^ 



■mm. 



yiappens on platfo 
^i^-partkxilarty dnr- 




,Peri error, 

WeVe 
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# the internal AT&T version 



Some of the functionality of the distributed VNC system is limited 
^A^en compared to the version we use within AT&T Laboratories 
Cambridge. This is not because we wish to deprive the rest of the 
worid of a more sophisticated system, but because we want VNC to 
be easy to download and set up. and this extra functionality would 
make that process more complicated v/ithout offering major gains to 
most users. 

So this information is given partly for interest's sake, and partly to 
explain some things you may find in the source code. If there is 
overwhelming demand for these features we may make them 
available, but this is not currently planned. 

CORBA 

Many of our systems are now linked together using CORBA. We 
didnt find a commercial implementatk>n of CORBA which met our 
requirements, and so we wrote our own, omniORB, which we have 
also made freely available. The VNC servers have a CORBA 
interface which allows them to be controlled by remote - systems. In 
particular, the interface exposes the name, address and other details 
of the server, allows control of the client connections, can perfonm 
remote shutdown, and initiate outgoing connections. 

Outgoing connections 

The simplest mode of operation for VNC is when a viewer initiates a 
connection to the server, but it can also operate in reverse. Some of 
our clients can t>e put into a listening* mode where they wait for 
connections from the server which are Initiated and closed down 
using the CORBA interface. 

External control 

This means that desktops can be displayed and 
hidden under the control of other systems. In 
particular we use information from our Active 
Badge system to display a users' desktop on a 
nearby monitor when they dick one of the buttons 
oh the.badg^rapdwittv iwaspundl^^ 





* Return or Enter 


Ox£f Od 


* Escape 


Ox £ fib 


* Insert 


Oxff 63 


* Delete 


Oxffff 


* Home 


OxCfSO 


* End 


Oxf f 57 


* Page Up 


Oxf f 55 


* Page Down 


Oxf f 55 


* Left 


Oxf f 51 


* Up 


Oxf f 52 


* Right 


Oxf f 53 


* Oo%m 


Oxf f 54 


* Fl 


Oxf fb€ 


• F2 
• 


Gxffbf 


* F12 


Oxf fc9 


* Shift 


Oxf fel 


* Control 


Oxf fe3 


* Meta 


Oxf fe7 


* Alt 


Oxf fe9 


*/ 





typedef struct ( 

CARD8 type; 

CARDS down; 

CARD16 pad; 

CARD32 key; 
} r f bKeyEventMsg ; 



- * always rfbKeyEvent ♦ / 

•* true if down (press) « false if up */ 

* key is specified as an X keysym */ 



idefine sz.rf bKeyEventMsg 8 



/* 

* PointerEvent - mouse /pen nove e^d/or butt.on press. 
*/ 

typedef struct { 

CARDS type; . * always rfbPo inter Event */ 

CARDS buttonMask; bits 0-7 are buttons 1-8, 0=up, l=down 

CARD16 x; 

CARD16 y; 
) rfbPointerEventMsg; 



tdefine rfbButtonlMask 1 
*de£ine rfbButton2Mask 2 
tdefine rfbButton3Mask 4 

tdefine sz_rfbPointerEventMsg 6 



/* 

♦ ClientCutText - the client has new text in its cut buffer. 
♦/ 

typedef struct { 

Q^BpS £ypp: /* always rfbQlientCwtText '*/ 





CARD32 length; 

/♦ followed by char textdength] */• 
> rfbClientCutTextMsg; 

#define sz^rCbGlientCutTe xtKsg 0 



/* 

* Union of -att-Tclient^o^servei—xnessaaes . 



typedef union ( 
CARDS type; 

rfbSetPixelForznatMsg spf; 
rfbFixColourHapSntriesMsg feme; 
rfbSetBncodingsKsg se; 
rfbFramebuf ferUsKlateRequestMsg fur; 
rfbKeyEventMsg ke; 
rfbPointerEventMsg pe; 
rfbClientCutTextMsg cct; 
) r f bCl ientToServerMsg ; 



/ ♦^^ --- 

* ServerCutText - the server has new text in its cut buffer. 
*/ 

typedef struct ( 

CARDE-type^— . , • always rfbServ.ecCutT£Xt_.V-. 

CARDS padl; 
CARD16 pad2; 
CARD32 length ; 

/* followed by char cexc [ier.gzh] */ 
} rfbServerCutTextMsg; 

tdefine sz_rfbServerCutTextMsg 8 

/♦ 

* Union of all server->client messages. 
*/ 

typedef .union { 
CARDS type; 

rfbFrainebuf ferUpdateMsg fu; 
rfbSetColourHapEntriesMsg seme; 
rfbBellMsg b; 

rfbServerCutTextMsg set; ' . - * 

) rfbServerToClientMsg; . . . "* ' 



* Hessage definitions (client -> server) 
♦ 

* SetPixelForznat - tell the 31F3 server the format in v^ich the client wants 

* pixels sent. 
♦/ 

typedef stiruct ( 

CARDS type; ** always rf bSetPixelFormat •/ 

CARDS padl; 

CARD16 pad2; 

rfbPixelForroat format; 
} rfbSetPixelFormatMsg; 



idefine sz^fbSet Pixel Forma tKsg (sz.rfbPixel Format + 4) 



* Fi>^olourK8^Entries - v^en the pixel fo^viat uses a. 'colour map*, fix 

* ,r^d-only colour znap entries. . ..-"r-Sr-:- r- - 



typede f s t rue t { 
CARDS type ; 
CARDS -pad^ 



CARDl 6 f i r s tColoxir ; 
CARD16 nColours; 



/• always rfbFixColcurMapEn tries */ 



/* Followed by nColours * 3 * CARD16 
- ri-, gi;--i3riT~r2, g2, b2, 3r3, g3, b3. 

} r £bF ixColourMapEntr iesMsg ; 

# define sz^rfbFixColourMapEntriesMsg 6 



•rzi, bnT gn — / 



m 



i3 

■ » • 



* SetEncodings - tell the RFB server which encoding types we accept. P-Jt them 

* in order of preference, if we have any. We aiay always receive raw 

* encoding, even if we don't specify it here. 



/♦ always z fbSet Encodings ♦/ 



typedef struct ( 
CARDS type; 
CARDS pad; 
CARDI6 nEncodings; 

/* followed by nEncodings * CARD32 encoding types */ 
} rfbSetEncodlngsMsg;' 

fdefine sz.rfbSetEncodingsMsg 4 



* Framebuf ferUpdateRequest - recjuest for a framebuffer update. If increnental 

* is true then the client just wants the chemges since the last update. If 

* false then it wants the whole of the specified rectwgle. 



typedef struct { 

CARDS type; 

CARDS incremental; 

CARD16 x; 

CARD16 y; 

CARD16 w; 

CARD16 h; 
> rfbFraiEkebufferUpdateRequestHsg; 

#de£ine sz.rfbFramebuf ferUpdateReguescMsg 10 



/• always rfbFraniebuf ferUpdateRequest •/ 



/♦ 

* KeyEvent - key press or release 
♦ 

* Keys are specified using the •keysyn- values defined by the X Window System. 

* most ordinary keys, the keysyia is the same as the corresponding ASCII 

* value. Other common keys arer 





/* ^ 

* RRE - Rise-and-Run- length Enccding. We have an rfbRREHeader structure 

* giving the number of subrectangles following. Finally the data follows in 

* the form [<bgpixel><subrect><subrect> . . . ) where each <subrect> is 

* ( <pixei ><r tDKec tang le> J . 
*/ 

typedef struct { 

CA RD3 2 nSubre cts ; 
} rfbRREHeader; * ' 

tdefine sz_rfbRKEHeader 4 



Q 



CoRRE - CoxEipacc RRE Encoding. We have an rfbRREHeader structure giving 

the number of subrectangles following. Finally the data follows in the form 

(<bgpixel><subrect><subrecc> . . . : where each <subrect> is 

(<pixel><rfbCoRRERectangle>] . This means that 

the v^ole rectangle nusc be ac :nost 255x255 pixels. 



m 

hi 



typedef struct ( 

CARDS x; 

CARDS y; 

CARDS w; 

CARDS h; 
} rfbCoRRERec tangle; 



#de£ine sz_r£bCoRR£Rec tangle 4 



Hextile Encoding- The rectangle is divided up into • tiles* of 16x16 pixels, 
starting at the top lefc going in 1 eft -to-right • top-to-bottom order. If 
the width of the reccangle is not an exact multiple of 16 t- h ** n the width of 
the last tile in each row will be correspondingly smaller. Similarly if the 
height is not an exacc !sulr:iple of 16 then the height of each tile in the 
final row will also be saailer. Each tile begins with a 'subencoding* type 
byte* which is a mask made up of a number of bits. If the Raw bit is set 
then the other bits are irrelevant; w*b pixel values follow (vribere w and h 
are the width and height of the tile) . Otherwise the tile is encoded in a 
similar way to ;iRE, except chat the position and size of each subrec tangle 
can be specified in just: tv/c bytes. The other bits in the mask are as 
follows : 



BackgroundSpecif ied - if set, a pixel value follows which specifies 
the background colour for chis tile. The first non-raw tile in a 
rectangle must have zhis bic set. If this bit isn't set then the 
background is the sarse as the last tile. 

ForegroundSpecified - if sec, a pixel value follows which specifies 

the foreground colour to be used for all subrectangles in this tile. 
If this bit is sec then the Subrec tsColoured bit must be zero. 




AnySubrects - if set, a single byte 'follows giving the nxunber of 

s\2brectangles follqwing._.. X£ not set, there are no sxibrec tangles (i.e. 
the whole .tile^ ls^'iuk t.^^:ajfeS: ^^§rQu nd colour) . r _ 

-^-.JJJ.^ji 




>Q 




SiibrectsColoured - if set then each suorectangle is preceded by a pixel 
value giving the colour of that -subrec tangle . If not set, all 
subrect singles are the same colour, the toregro^^d colour; if the 
PoregroundSpecified bit wasn't set then the foreground is the sazoe as 
the last tile, , 



The position and size of each subrectangle is specified in two bytes. The 
Pack macros below can be used to generate the two bytes from x, y« w« h, 
and the Extract macros can be used to extract the x. y« w^ h values from 
Jch.G two bytes . . 



♦define rfbKextileRaw (1 << 0) 

♦define rf bHextileBackgroundSpecif ied (1 << 1) 

♦define rfbHextileForegroundSpecif ied (1 << 2) 

♦define rfbHextileAnySubrects (1 << 3) 

♦define rfbHextileSubrectsCo loured (1 « 4) 

fjl ♦define rf bHextilePackXY(x,y) ( ( (x> « 4) i (y) ) 

□ ♦define rfbHextilePackWH(w,h) ((((w)-l) «4) | ((h)-l)) 

1^ ♦define rfbHextileExtractX(byte) ((byte) » 4) 

♦define rfbHextile£xtractY(byte} ((byte) & Oxf) 

♦define rfbHextileExtractW(byte) (((byte) » 4) * 1) 
:« ♦define x-fbHextileExtractH (byte) (((byte) & Oxf) + 1) 

Ul 

W /* 

* SetColourHapEntri-es * these messages are only sent if the pixel 

>3 * format uses a "coloxir map* (i.e. trueColour false) and the client has not 

* fixed the entire colour map using FixColourMapEntries . In addition they 
13 * will only start being sent after the client has sent its first 

p * Framebuf ferUpdateRe<3uest. So if the client always tells the server to. use 

* trueColour then it never needs to process this type of message. 
*/ 

typedef struct { 

CAED8 type; /♦ always r fbSetColcurHapEntries */ 

CARDS pad; 
CARD16 firstColour; 
CARD16 nColours; 

/* Followed by nColours * 3 ♦ CARD16 

rl, gl, bl, r2, g2, b2, r3, g3. b3 m. on, gn */ 

) rfbSetColourMapBntriesMsg; 

♦define sz^rfbSetColourMapEntriesMsg 6 



* Bell — ring a bell on the client if it has one. 
*/ 

typedef struct { 



CARD8 type; /• always rfb3ell •/ 

) rfbBellMsg; . * 




* Fo llowing the server initial isar ion m essage it 's up to the client to send 
' whichever protocol messages it v.-ahes . *rypical ly it will send a 

* SetPixelFormat message and a SetEncodings message, followed by a 

* FramebufferUpdateRequest. Froai then on the server will send 

* FramebufferUpdate messages in response to the client's 

* ^^a°>^ ^fferUpdate Reque st messages. The client sh ould send 

^ rrameoufferUpdateRequest messages with incremental set ' to true wherTTt^ hi"s " 

* finished processing one Franebuffer Update and is ready to process another 

* With a fast client, the rate at which Framebuf f erUpdateRequests are sent 

* should be regulated to avoid hogging the network. 
♦/ 



* 

* Message types 

/* server -> client */ 

tdefine rfbFraroebuf ferUpdate 0 
#define rfbSetColourMapEntries 1 
tdefine rfbBell 2 
tdefine rfbServerCutText 3 



/* client! -> server */ 
tdefine rfbSet Pixel Format 0 

tdefine rfbFixColourMapEntries 1 /* not currently supported */ 

tdefine rfbSet Encodings 2 

tdefine rfbFramebuf ferUpdateRequest 3 

tdefine rfbKeyEvent 4 

tdefine rfbPointer Event 5 

tdefine x-fbClientCutTexc 6 



/*********^*^*********n*^******^*^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 
* 

* Encoding types 
* 

tdefine rfbEncodingRaw 0 • 
tdefine rfbEncodingCopyRect 1 
tdefine rfbEncodingRRE 2 
tdefine rfbEncodingCoRRE 4 
tdefine rfbEncodingHextile 5 



m 




Server -> client message definitions 



* FraroebufferUpdate - a block of rectangles to be copied to the framebuf fer. 

* This messa ge cons ists of a head er giving the niunber of rectan<y les of pivp? 
data followed by the rectangles themselves. The header is padded so that 

* together with the type byte it is an exact multiple of 4 bytes (to help 

* with alignment of 3 2 -bit pixels) : 
*/ 

typedef struct { 

CARDS type; /♦ always rf bFramebuf f erUpdate */ 

CARDS pad; 
CARD16 nRects; 

/* followed by nRects rectangles */ 
} r f bPramebuf ferUpda teMsg ; 



# define sz_rfbFrfiunebufferUpda teMsg 4 
Jl /* 

^ * Each rectangle of pixel data consists of a header describing the position 

* si^® of rectangle and a type word describing the encoding of the 
^ * pixel data, followed finally by the pixel data. Note that if the client has 

not sent a SetEncodings message then it. will only receive raw pixel data. 

♦ Also note again that this structure is a multiple of 4 bytes. 



^ typedef struct { 

's^ rfbRectangle r? 

•0 CARD32 encoding; /* one of the encoding types rfbEncoding. . 

> rfbFramebufferUpdateRectHeader; 

♦define sz_rfbFramebuf ferUpdateRectHeader (sz^rfbRec tangle 4) 



* Raw Encoding. Pixels are sent in top-to-bottom scanline order, 

* left-to-right within a scanline with no padding in between. 



/• 

CopyRect Encoding. The pixels are specified sisc^ly by the x and v position 
• of the source rectangle. 
•/ 

typedef struct { 

CARD16 srcX; 

CARD16 srcY; 
> rfbCopyRect; 



tdefine sz_rfbCopyRect 4 




. J** 

•5 



#define sz_rfbPixel Format 16 



Initial handshaking messages 



/* 

* Protocol Version 



* The server always sends 12 byces to start which identifies the latest RFB 

* protocol version number which Lz supports. These bytes are interpreted 

* as a string of 12 ASCII characters in the forxoat "RFB xxx.yyy\n' where 

* XXX and yyy are the major and niinor version numbers (for version 3.3 
Iji * this is -RFB 003.00S\n-). 

!«i * "Tl^® client then replies with a similar 12-byte message giving the version 

^ * nuihber of the protocol which should actually be used (which may be different 

!is * to that quoted by the server} . 

\U * 

* It is intended that both clients and servers may provide some level of 

* backwards compatibility by this mechanism. Servers in particular should 

Ui * atten5>t to provide backwards coirpatibility, and even forwards compatibility 

M * to some extent. For. example if a client demands version 3,1 of the 

□ * protocol, a 3.0 server can probably assume that by ignoring requests for 

* encoding types it doesn't understand, everything will still work OK. This 

* will probably not be the case for changes in the major version number. 



* The format string below can be used in sprint f or sscanf to generate or 

* decode the version string resoectively . 
*/ 

tdefine rfbProtocolVersionForroat -RFS %03d.%03d\n" 
fdefine rfbPrdtocolKajorVersion 3 
tdefine rfbProtocolMinorVersion 3 

typedef char rfbProtocolVersionMsgil3 3 ; /* allow extra byte for null ♦/ 
fdefine sz_rfbProtocolVersionMsg 12 



* Authentication 

* Once the protocol version has been decided, the server then sends a 32-bit 

* word indicating whether any authentication is needed on the connection. 

* The value of this word determines the authentication scheme in use. For 

* version 3.0 of the protocol this may have one of the following values: 



♦define rfbConnFailed 0 
tdefine rfbNoAuth 1 
tdefine rfbVncAuth 2 




^Mc!r".\'^ - r fbConnFai led gi.\v^S/~:^j^:EQi^^ 




:.^onnection faiied>..(e^^;taie.;^;es£^^ 



rfbNoAulih: 
rfbVncAuth: 



cannot support the desired protocol version) . This is 
followed by a string describing the reason (where a 
string is specified as a 32-bit length followed by that 
many ASCII characters) . 



No authentication is needed. 

The VNC authentication scheme is to be used. A 16-byte 
challenge follows, which the client encrypts as 
-appr-oEH:4ra^e- using the-password and sends the r^uttirrg 
16-byte response. If the response is correct, the 
server sends the 32-bit word rf bVncAuthOK. If a simple 
failure happens, the server sends rfbVncAuthFailed and 
closes the connection. If the server decides that too 
many failures have occurred, it sends rfbVncAuthTooMany 
and closes the connection. In the latter case, the 
server should not allow an immediate reconnection by 
the client. 



tdefine rfbVncAuthOK 0 
tdefine rfbVncAuthFailed 1 
tdefine rfbVncAuthTooMany 2 



* Client Initialisation Message 

* ^^^u""® client and server are sure that they're happy to talk to one 
another, the client sends an initialisation message. At present this 

^ message only consists of a boolean indicating whether the server should try 

to share the desktop by leaving other clients connected, or give exclusive 
^^access to thxs client by disconnecting all other clients. 

typedef struct ( 

CARD8 shared; 
} rfbClientlnitMsg; 

*define sz_rfbClientlnitMsg 1 



* Server Initialisation Message 

* ^^^o''-*^? client initialisation message, the server sends one of its own. 
^ This tells the clxent the width and height of the server's framebuffer, 
^^its pixel format and the name associated with the desktop. 

typedef struct { 

CARD16 fraxnebufferWidth; 
CARD16 framebufferHeight; 

^f^n^^®^^""?^^ format; /* the ser-^er's preferred pixel format */ 

CARD32 nameLength; 

/♦ followed by char name (nameLength] */ 
} rfbServerlnitMsg; • 



m 
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Copyright (C) 1997, 1998 Olivetti fit Oracle Research Laboratory 

This is free so ftware; you can redistribute it and/or modif y 

xt under the tenos of the GNU General Public License'aTi^lished by 
the Free Software Foundation; either version 2 of the License, or 
(at your option) any later version. 

This software is distribut ed in the hope that it_willJfee_aSfif.uX, 

but WITHOUT ANY WARRANTY; without even the implied warranty of 
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
GNU General Public License for nore details. 

You should have received a copy of the GNU General Public License 
along with this software; if not, write to the Free Software 
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, 
USA • 



rfbproto.h - header file for the RFB protocol version 3.3 

I V®®.^_^^®® CARD<n> for an n-bit unsigned integer, INT<n> for an n-bit sioned 
integer (for n * 8, 16 and 323 . 

• 'I * 

L^l * All multiple byte integers are in big endian (network) order (most 

* Significant byte first) . Unless noted otherwise there is no special 
alignment of protocol structures- 

!f1 * initial handshaking is done, all messages start with a type byte, 

7ri ^ iw^''^^^'^ followed by message-specific data. The order of definitions in 

this file is as follows: 

(1) Structiires used in several types of message. 

* (2) Structures used in the initial handshaking. 

* (3) Message types. 

* (4) Encoding types. 

* (S) For each message type, the- form of the data following the type byte. 

Sometimes this is defined by a single structure but the more complex 
messages have to be explained by comments. 



•* »•» 

* Structures used in several messages 

/* 

I f^""^"^^ used to specify a rectangle. This structure il r^Itiple'of 4 
bytes so that it can be interspersed with 32-bit pixel data without 
affecting alignment. 

*/ 

t:yi>edef-. Struct ( * . 



i 



CARD16 w; 
CARD16 h; 
} r fbRec tangle ; 

•#de £ine 3 g_ r£bRec tangle 8 



Structure used to specify pixel format. 
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typedef struct { 

CARDS bitsPerPixel; /* 8,16,32 only '/ 

CARDS depth; /* 8 to 32 */ 

CARDS bigEndian; /♦ True if zailti-byte pixels are interpreted 

as big endian, or if single-bit-per-pixel 
has most significant bit of the byte 
corresponding to first (leftmost) pixel. Of 
course this is meaningless for 8 bits/pix ♦/ 

CARDS trueColour; /* If false then we need a •colour map' to 

convert pixels to RGB. If true, xxxMeuc and 
xxxShift specify bits used for red, green 

and blue */ 

/* the following fields are only meaningful if crueColour is true */ 



CARD16 redMax; 

CARD16 greenMax; 
CARD16 blueMax; 



/♦ majcimua red value (= - 1 vmere n is the 

number cf bits used for red). Note this 
value is always in big endian order. */ 

/* similar for green */ 

/* and blue */ 



CARDS redShift; /* number of shifts needed to get the red 

value in a pixel to the least significant 
bit. To find the red value from a given 
pixel, do the following: 

1> Swap pixel value according to bigEndian 
(e.g. if bigEndian is false £uid host byte 
order is big endian, then swap) - 

2) Shift right by redShift. 

3) AND with redMax (in host byte order). 

4) You now have the red value between 0 and 
redKax. «/ 



CARD8 greenShift; /• similar for green ♦/ 

CARDS blueShift; /• and blue •/ 

CARDS padl; 
CARD16 pad2; 
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53.3 BeU 

Ring a bell on the client If it has one. 



No. of bytes 


Type 


[Value] 


Description 


1 


CARDS 


2 


message-type 
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53.4 ServerCutText 

The server has new ASCII text in its cut buffer. End of lines are represented by the 
linefeed / newline character (ASCII value 10) alone. No carriage-return (ASCII value 
13) is needed. 



No. of bytes 


Type 


[Value] 


Description 


1 


CARDS 


3 


message-type 


3 






padding 


4 


"CSKDB^ — 




length ■ 


length 


CARDS array 




text 
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No. of bytes 


Type (Value] 


Description 


n 


CARD<8n> 


backgroimd'pixel'value 



where 8n is the number of bits-per^pixel as agreed by the client and server - 
either in the Server/nitialisation message (section 5.L4) or a SetPixelFor- 
mat message (section 5.2. 1 ). The first non-raw tile iira rectangle must have 
this bit set If this bit isn't set then the background is the same as the last 
tile. 

ForegroundSpecified - if set, a pixel value follows which specifies the fore- 
ground colour to be used for aU~subrectingiesln 



No. of bytes 


Type 


[Value] 


Description 


n 


CARD<8n> 


foreg round'pixel'Value 



If this bit is set then the SubrectsCoIoured bit must be zero. 

AnySubrcds - if set, a single byte follows giving the number of subiectangles 
following: 



No. of bytes 


Type 


[Value] 


Description 


1 


CARD 8 


number-cf-subrectangles 



If not set, there are no subrectangles (Le. the whole tile is just solid back- 
ground colour). 

SubrectsCoIoured - if set then each subrectangle is preceded by a pix^ vahie 
giving the colour of that subrectangle, so a subrectangle is: 



No. of bytes 



n 
1 
1 



Type 



[Value] 



CARD<8n> 

CARDS 

CARDS 



Description 



subrect-pixei'Value 

x-and-y-position 

widthHind'height 



If not set, all subrectangles are the same colour, the foiegroimd colour; if 
the ForegroundSpecified bit wasn't set then the foreground is the same as 
the last tile. A subrectangle is: 



No, of bytes 



Type [Vaiuel 



CARDS 
CARDS 



Description 



x-and-y-position 
widih-and'heighi 



The position and size of each subrectangle is specified in two bytes, x-^ind-y- 
position and width-and-height. The most-significant four bits of x-and-y-podtion 
specify the X position, the least-significant specify the Y position. The most- 
significant four bits of width-and-height specify the width minus one, the least- 
significant specify the height minus one. 





53 SERVtK TO CLIENT MESSAGES 
53Jt SetColourMapEntries 

Currently there is little or no support forcolQjiir maps. Some preliminary work was 
on this, but is incomplete. It was intended to be something like this: 

When the pixel format uses a "coloufmap', this message tells the client 
that the specified pixel values should be mapped to the given RGB inten* 
sities. The server may only specify pixel values for which the client has 
not already set the RGB intensities using FixCoiourMapEntries (section 



Currently, colour maps are only supported at all by the X-based server. 



• 5.2.2). 



No. of bytes 



Type 



[VBdue) 



Description 



1 
1 
2 
2 



CARD16 
CARD16 



CARDS 



1 



message-type 
padding 
first-colour 
number-of-coiours 



followed by number-of-coUmrs repetitions of the following: 



No. of bytes 



Type 



[Value] 



Description 



2 
2 
2 



CARD16 
CARD16 
CARD16 



red 

green 

blue 
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S3A FramebufferUpdate 

A framebuffcr update consists of a sequence of rectangles of pixel data which the client 
should put into its framebuffer. It is sent in response to a FramebufferUpdateRequest 
from the client Note that there may be an indefinite period between the Framebuffer- 
UpdateReques't md'fhc FrcunebufferUpdate. ~ 



No. of bytes 


Type 


[Value] 


Description 


1 


CARDS 


0 


message-type 


1 — - 






padding 


2 


CARD16 




nuntber-of-rectangles 



This is followed by number-of-rectangles rectangles of pixel data. Each rectangle con- 
sists of: 



No. of bytes 


Type 


[Value] 


Description 


2 


CARD16 




x-position 


2 


CARD16 




y-posiiion 


2 


CAR016 




width 


2 


CARD16 




height 


4 


CARD32 




encoding-type: 






0 


raw encoding 






1 


copy rectangle encoding 






2 


JSIKE encoding 






4 


Coi^AE encoding 






^ 5 


hextile encoding 



followed by the pixel data in the specified encoding. 

• For rctw encoding the data consisu of width x height pixel values. Hie values 
simply represent each pixel in left*to-right scanline order. 

• For copy rectangle encoding the data consists of: 



No. of bytes 



2 
2 



Type 



[Value] 



CARD16 
CARD16 



Description 



src-X'posmon 
src-y-position 



• For RRE encoding the data begins with the header 



No. of bytes 



4 
n 



Type 



[Value] 



CARD32 
CARD<8n> 



Description 



number-of'Subrcctangies 
background'pixel-valiie 



where 8n is the number of bits-per-pixel as agreed by the client and server- ei- 
ther in the Serve rlnitialisatlon message (section 5. 1 .4) or a SetPixelFormat mes- 
sage (secdon 5.2.1). This is followed by number-of-subtectangUslastajoces of 
the following structure: 
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No. of bytes 


Type (Value] 


Description 


n 
2 
2 
2 

2 


CARD<8n> 

CARD16 

CARD16 

CARD16 

CARD16 


subrect-pixel'Value 

X'position 

y-position 

width 

height 


For CoRRE encoding the data begins with the header 


- No.-of-by tes- 


^ype- [Value! 


Description- - - 


4 

n 


CARD32 
CARD<8n> 


number-of'Subrectangles 
background'pixel-value 



where 8n is the number of bits-per-pixel as agreed by the client and server - ei- 
ther in the Serverlnitialisation message (section 5. 1 .4) or a SetPixelFormat mes- 
sage (section 5.2.1). This is followed by number-of-subrectangles instances of 
the following structure: 



No. of bytes 


Type [Value] 


Description 


n 


C::ARD<8n> 


subrect'pixel'value 


1 


CARDS 


x-position 


1 


CARDS 


y-posiiion 


1 


CARDS 


width 


1 


CARDS 


height 



For hextUe encoding the rectangle is divided up into tUes of 16x16 pixels, start- 
ing at the top left going in left-to-right, top-to-bottom order. If the width of the 
rectangle is not an exact multiple of 1 6 then the widdi of the last tile in each row 
will be correspondingly smaller. Similariy if the height is not an exact multiple 
of 16 then the height of each tile in the final row will also be smaller. 

Each tile begins with a subencoding type byte, which Is a mask made up of a 
number of bits: 



No. of bytes 




Description 



subencoding-mask: 
Raw 

BackgroundSpec^ied 
ForegrouadSpec^d 
AnySubrects 
SubrectsColonred 



If the Raw bit is set then the other bits are irrelevant; xoidth x height pixel values 
foUow (where width and height are the width and height of the tile). Otherwise 
the other bits in the mask are as follows: 



BackgroundSpecffied - if set, a jmxcI value follows which specifies the back- 
ground colour for this tile: 
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5^.7 ClientCutText 

The client has new ASCII text in its cut buffer. End of lines are represented by the 
linefeed / newltne character (ASCII value 10) alone. No caniage-retuin (ASCII value 
13) is needed. 



No. of bytes 


Type 


(Value] 


Description 


1 


CARDS 




message-type 


3 






padding 


4 


CAjRD32 




length 


length 


CARDS array 




text 



1 --- ' . ■-- - 
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5J Server to client messages 
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it 

O 
-i 
o 
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5*2^ KeyEvent 

A key press or release. Down-flag is non-zero (true) if the key is now pressed, zero 
(false) if it is now released. The key itself is specified using the ^ysym** values defined 
by the X Window System. For full details, see The Xlib Refetence Nfanual. published 
by O'Reilly & Associates, or see the header file <Xll/keysymdef V& lrom any X 
Window System installation. 



No. of bytes 


Type 


(Value] 


Description 




CARDS 


4 


message-type 


I 


CARD8 




down^flag 


2 






padding 


4 


CARD32 




key 



For most ordinary keys, the -kcysym" is the same as the corresponding ASCII value. 
Other common keys are; 



Key name 


Keysym value 


Keyname 


Keysym value 


Backspace 


OxflOS 


Fl 


Oxffbe 


Tab 


0xfH)9 


F2 


Oxffbf 


Return or Enter 


OxffOd 


F3 


OxifcO 


Escape 


Oxfflb 


F4 


Oxffcl 


Insert 


Oxff63 






Delete 


OxffIT 


F12 


0xffc9 


Home 


0xff50 . 


Shift (left) 


Oxffel 


End 


OxffS? 


Shift (right) 


0xffe2 


PageUp 


OxffSS 


Control Gcft) 


0xffe3 


Page Down 


Oxff56 


C!ontrol (right) 


0xffe4 


Left 


0x«51 


Meta (left) 


Oxffe? 


Up 


Qx£f52 


Meta (right) 


OxffeS 


Right 


Oxfr53 


Alt (left) 


0xffe9 


Down 


Qxff54 


Alt (right) 


Oxffea 
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5^.6 PointerEvcnt 

Indicates either pointer movement or a pointer button press or release. The pointer is 
now at (X'posiiion, y-posititm)^ and the current state of bunons I to 8 are represented 
by bits 0 to 7 of button^mask respectively, 0 meaning up, 1 meaning down (pressed). 



No. of bytes 


lype [Value] 


Description 


1 
1 
2 


CARDS 5 
CARDS 
CARD16 
CAR016 


message-type 
button-nuxsk 

X'position 

y-position 


- 2 



\ y 

1^ 



'si 
'•3 

m 



. I connected to my Unix server mml ]ust see a grey desktop 
with a cursor. Where's my normal X environment? 



After the vncserver script has started the Xvnc server, it then runs your 
--Avnc/^startup script. By default this will try to start the twm wirulow manager, 
but if twm isnt on your path; or if you prefer something else, you can edit 
xstartup. The log file may also give you dues about what is happening. 

Q. The log file is showing anrerror message from xrdb / Xlib. 

By default, the first thing your xstartup script does is to run xrdb to load your 
resources. So if the Xvnc sen/er has not started for any reason, the xrdb is 
often the first thing to notice it arKi print an error. (Though if you!re getting^ 
'command not found* message, then xrdb Is probably not on your path - you 
need to find where it is on your system and add it.) 

If you get something like 'connection refused or 'Canl connect ermo =111', 
the Xvnc server probably isn*t there. So you should check wtiether the Xvnc 
process is actually running, and whether there is anything eartier in the log file 
indicating why it might have died. By far the most comnrK>n reason for the 
server rK>t starting is that it cant find the fixed* font (see above). Other 
possibilities are that the server has quietly crashed, or that it is taking a very 
tong time to start up. The vncservrer script has a 3-second delay before 
running xstartup, but in extreme cases this may not t>e enough. Lastly, the 
DISPLAY variable used by vncserver is based on the results given by the 
'uname - n' command. If your applications cannot resolve this to the right IP 
address, perhaps because of funny settings in /etc/hosts, then they wont l>e 
able to connect 

If you get a 'Qient is not authorized to connect to Sender* or similar message, 
there's something wrong with the X authority setup - perhaps xauth is not on 
your path? You could try using xhost to bypass this temporarily, bxst we 
wouWnt recomend this as a long-term solutk>n. There shouki be some 
indication in the log file if xauth has failed. 

Q. The Java client doesnt work in my browser. 

Several Java implementations have bugs which upset the VNC applet We 
recommend Internet Explorer 4 • weVe had good results with this on both 
Windows machines and Macs. Netscape Navigator 3 has a bug which can 
cause problems; rf you get the 'Method setClip not found* error, try pressing 
Reload. 

Q. My viewer failed to connect to my server! 

VNC relies on a correctty-configured arKJ operational TCP/IP networic, so 
please make 100% sure that your TCP/IP setup is right before you start asking 
questions on the mailing list Here are some things you should check before 
assuming It's a VNC problem; consult your local expert If you doni know how 
to check them: 

e Can you ping the server machine from the dient? 
e is the VNC sen/er definitely ainning on the sen/er machine? 
• The senrer listens on port 59004displaynumber. Can you telnet to this 
port from the client nr^chine? 
. . e -Have you specified the address correctly to the viewer? Dk^ you, 
f^-^^ieh^wnber the display numbei?.- ^r^^- — '^^^jj ^. i^jji^ '^r 

%^s4}$9r^Wyer name known to tfie 'X>NS?' <TryIUsii1^^ address 




eval • require • sys /socket .ph* 
Your first option is to change this to: 

($] >= 5.0) ? eval 'use Socket" 
• sys/ socket .ph* * ; 

if this doesnl work, particularly on S.u.S.E., you could 

eval 'require •liilixx/socket .ph" * ; 
or check your Pert installation to see if sockeLph is to be fourid in another 
directory. 



: eval " require 



tiy. 



Remember that vncserver is only a convenient wrapper around 
causes you problems, feel free to discard it and run Xvnc directly. 



Xvnc. If It 



Q. I started the X server using vncserver, but It dies with a 
message "Couid not open default font 'fixed'. *" 

The fixed* font is needed for the server to start - if it cant find it, you need to 
specify the correct font path for your machine in the Vncserver' scr^>t If 
you're not sure what the path shoukl be, type "xset q* from witftin a nomial X 
session. One of the things reported is the font path used by your current X 
server, which is generally the right thing to use for Xvnc. On some platforms 
you may need to use a colon as a separator in the font path instead of a 
comma. If you're on a recent version of Unux but still using VNC version 3.3.1 , 
you may have compressed fonts which VNC doesnl understand. Either 
upgrade or see the OkJ FAQ . 

The VNC server can also get upset if you have directories on your font path 
which dont actually exist on your system. Make sure you remove tfiose. Also 
note that the Xvnc sewer, by default, acts as if it has a resolution of 1 00dpi. 
Some RedHat installatibns, for example, only tristall 7Sd^ fonts, so you may 
need to install the mis^ng font RPMs from yOur-distnl>u6on or use the 
option to Xvnc. ' * 

Q. I get errors like "failed to bind listener" and "Failed to 
establish all listening sockets" in the log file. 

This is prbbat)ly due to the permissior^ on Amp/J(11-vnbc Youmayvirellsee 
this if you update to Solaris 2.7. for example. See ttie section below enfiUed 
"Why can I only run vncserver/Xvnc as root?*. 

Q. Vncserver seems to be dying quietly \^thout putting any 
messages in 0ie log file. 

Check tfiat the Xvnc process really has died. If so, then check ttud your VNC 
font path (set by unoorrunenting Fines in the vncserver scnpf) only kidudes 
directories which actually exist The XFree86 code in Xvnc seems to have a 
problem which causes the server to die quietly if non-existent directories are 
searched. You could also nK>dify the vncserver script to check tor and 
remove non-enstent directories. See Bruce A. Mah's patch for an eocample. 

Q. My Solaris/HP-UX Xvnc dies with a core dumpi 

There is a bug in XReeSe (on which Xvnc is teased) whidj^dniakes Solaris 
Sjervers ve ry unrelsable if Ihey have a pbcel depth pf 1 6:^1}^^^ -iiefith cfiBon 
[ilKHir server with a di^?4h^ fine. Wtfve 



Do you have any firewalls or proxies in tflffway that oould be bloddng 
acess? 

^ If using the java dient» did you remember to specify the correct port as 

part of the URL? (eg. httpy/snoopy:5800 )? 
^ Can you try running eittier the server, or the client, or both, on different 

machines on your rtetwork to find whether the problem is at one end or 

the others 

# nanynii try running the software on a different architecture? eg., if you 

are having problems viewing a PC from another PC, can you try 
connecting from a Unix machine? 



Problems running the programs 

Q. My X VNC server is working, but 1 dont see my normai 
environment. How can i change the Window manager etc? 

The wIrKiow manager is started by the -/.vncAcstartup script Weusetwm, as 
this is avaBable on almost ail Unix platforms. Edit the script if yoCfd rather 
replace it with somethbig else. On nriariy platfbrrns you can, as aiiiaRemativ^ 
just make xstarti^) a link to wfiatever script rK>nmally starts your X environment 
If you want to be nK>re sophistk^ated, you can spedfy the -name op66t\ to 
vncsen/er, and then take different actions in tl^ xstartup script based on the 
name giveri. R>r example: 

case ■$VNCDBSKTOP- in 

kde) 

stax-tJcde & 



xt:erm -geometry 40x10-1-40^40 -Is -title -SVNCDESKTOP D- 
twm & 



esac 

Q. Why can 1 only run vncserver/Xvnc as root? 

The most likely reason for this is that Xvnc cant create the unbc domain socket 
(the path for this unbc domain socket is usually /tmp/X\ 1 -urvx/Xn). Try making 
sure that users can write to this directoiy t>y making it worid-writable, i.e. 
"chrrKxla+w Amp/JCII-unix". hiote that to avokl a security k)ophole the 
"stk:ky bit" shoukJ also be set on the directoiy by doing 'chmod 044 
/tmp/.X11-unix*. If you dont do this then someone else k>gged in to tfie same 
machine may be at>le to intercept the X protocol and thereby access your 
desktop arxl 8fKX)p on n, etc. AnaltemafivetetosettheXvncbffiaiytohave 
the same perniisstoris asyotjr iKxriial XsevVer, t>ut this may be more of a 
security risk. 



rated this way. but we have no plans t(^^P so. It shouldn't be too difficult, 
if you have the full source code for your X server. Xvnc is basically XFree86 
with the hardware-dependent bits taken out and VNC put in their place, so it 
doesnl have drivers for any graphics cards. You could have a look at the 
Xvnc source code to see which bits have been added to the standard 
.XFreeSe. and make the equivalent changes on your X server. 
We tend to run all our X sessk)ns as VNC sessfons and onfy use the local X 
server to run the viewer. If s very fast when on the same machine as the 
served If you feel that if s overidtrtorun two X servers on the same machine, 
you might consider Qanesh Varadarafan's svgaiib-based viewer, available 
from the contribs page. 

Q. What X Visual doe^Xvncuse? 

By default vncserver will start Xvnc with the same depth as the current X 
display, if there is one, or 8 bits deep if there isn't WeVe tried to steer dear c 
colour maps as much as possible and rK)mr)ally use "true cokHir*. even when 
there are only 8 bits per pixel. 

Unfortunately some X appTicatkins donl cope too well with an 8 bit TrueColor 
visual. You can make Xvnc use the nx>re normal PsoudoCok>r visual by 
giving a '-cc 3* option to vncserver. 

Q. Can I cut and paste between the viewer and the server? 

VNC supports copying arKi pasting of ASCII text in both cfirectkxis, provkled 
the viewer and server allow it When the clipboard changes on the machine 
running the viewer, the changes are copied to the server and vice versa. 
Some notable exceptions: 

• X has more than one method of using the cTipboard and different 
applications do it different ways. Emacs and xterm shouki just work. If you 
find that your X application doesnt work via VNC, you can generally use 
the xcutsel program to copy the cTipboard between the different X 
methods, VNC uses Cut_BufferO, so tf you sel^ text In Unix Netscape, 
for exarrple, you may need to dick "Copy PRIMARY to 0' before it is 
accessible at the otfier end of the VNC fink. 

e Java applets running in the browser cannot access the clipboard of the 
machine on which they are running, so the Java viewer has a dq^boand 
tMJtton. This pops up a window displaying the contents of the remote 
cTipboard, which shouki allow you to manipulate it locally. 

The code to do copying from the X server to the viewer dklnt make it in tf)e 
origir\al version 3.3^. If s back in 3.3^R2 and later, so upgrade if you haven't 
already! 

Q« There's a memory leak In Xvnc! 

This occurs in verskxi 3.3^r2 and earlier, tnit is fixed in 3.3^r3 and later 
versk>ns. if you're using an okSer distritnifion you can find a patch for it here 



(a. Can I. run. the Windows server before anybody hasJoc^fed 



le keyboard doesnt work / keys oostrange thingsl 



There is one common problem which can cause this. If a modifier key, such as 
Shift, Ctrl or Alt, is pressed, and the viewer window then loses focus or dies, 
the *key release' message never gets to the viewer and hence never gets to 
the remote server. The remote machine will then think that M is Ctri-M etc. 
We have done various things to reduce the chance of this happening; the 
viewers release various modifiers automatically when they lose focus, for 
example, but it can still occur and can be confusing when it does. The 
solution is easy: simply press and release the modifier key which is stuck, if 
you dont know whteh it is, then tiy them one at a time. 

Q. Most of my Windows apps work fine remotely, but this one 
doesnt update Its window... 

WinVNC can use a variety of hints to guess when a particular area of the 
screen has changed. The most useful is the occun^enoe of a WM.PAIf^ 
message in an application, ftot all applteations use these messages, though; 
ttie Windows dock is a good example. 

in the registry WinVNC has a list of application names, and which tMngs to use 
as update dues. A few standard appllcatfons are set up by the 'Install default 
registry settings' In the WinVNC section of the Start Menu; it tells WinVNC to 
k>ok for timer messages from the dock, for example. Make sure you install 
tfiese rf you havent already. Any other apps you run win appear in the 
registry, so you can easily tweak the settings. For more info, see the WinVNC 
documentation. 

CL WinVNC is putting a huge load on my PC! 

Firstly, WinVNC shouM have negligible irrtpact when notxxly is connected to 
it It does practically nothing in this state. If you find that it is running at 
somettiing dose to 1 00% CPU when ttiere is a remote connection .check the 
Update Handling in the Properties dialog t>ox. The default settings shoukl be 
fine in most circumstances. If you have either (a) Ticked 'PoB Full Screen* or 
(b) Ticked 'Pofl Foreground Window* or 'PoU Window Under Cursor* witfiout 
having "Poli Console Windows Onl/ ticked, then the toad will be much higher, 
^e also the section betow on *How do I make VNC go fasterr. 

Q. WinVNC dies, or causes other applications to die, after a 
short Uwe when a viewer Is connected. 

Some screen savers, particularly on Windows 95, do not interoperate well with 
WmVNC. Try disabrtng all screen savers on the machine running the senrer 
md see if that fixes it 

Q. IMy remote Windows display is appearing in a very garbled 
form. 

TbeiB can be problems with WinVNC t>eing unable to detect changes to the 
sssBBti on certain appFtcatfons. as mentioned in the prevtous question, but 
there shoukJ not generally be senous screen corruption. Make sure you have 

tiie latest service packs instailed for your OS and experiment with different - 

^mSm drivers. WinVNC relies on various aspects of the vkleo card and driver; 
Bi particular its abifity to BitBIt conectiy , and several users have solved thett* 
pR^rfems by updating the driver. 



Q Jj^y cant I unlock my NT workstatf^^motely? Why can't I 
st^nhe Screensaver remotely? Why dolsnt Ctrl-Alt-Del 
woric? 

Make sure you are running a recent version of VNC. and that you are 
running it as a service . From some platforms you wilt not be able to type 
Ctrl-Alt-Del directly, because it will be caught by the local machine. The 
Windows viewer, for example, has an option on its menu to send a 
Ctit-Alt-Del to the remote host. In some situations, you will find that something 
like Ctrl-Alt-Backspace or Ctrl-AK-<Numeric keypad Del> may work instead. 
Screensavers sometimes use a different resolution and so can disconnect you 
when they stop or start - see the next question. 

Q. When I connect using VNC and then log into my Windows 
machine, I get disconnected and have to reconnect! 

Sometimes logging in will involve a change in screen resoiutk>n, if ttte user's 
display seffings are different from the defaults. H this happens, the server will 
disconnect you and you wifl need to reconnect to get the new screen size. 
Just occaskxially on NT, the mode seems to change resolution temporarily as 
you tog in, and if WinVNC happens to see this you can also be disconnected, 
even if the final resolution dianges. 

If the user has set a different display number in their personal WinVNC 
properties dialog you wiH also be disconnected. 

Q. I have troubles sending Ctrl-Alt-Del to a Windows server. 

e Ctrl-Att-Del will only be recognised by a Windows NT VNC server, and 
only when VNC is running as a service. On Win95/98, it suspends aB 
processes, mduding the VNC sender, so it wouldn't be rrux^h use! 

e The Windows and Java viewers have menu options to serxi Ctrt-AR-Del, 
so they dont get interpreted locally. 

• If you are using the Mac or X-based viewer, you should ^ist be able to 
type the keys, t>ut some platforms seem to catch the keystrokes. If this is 
the case for you, I'm afraki you'll have to work out how to stop it! Itmight 
be worth trying slight variations (eg. the right Ctl key, or a different 
Del/Delete key, if you have one). 

Q. The dead keys dont work on my keyboard 

Theywill soonl If s quite a challenge working out how to do intemafional 
keyboard support across different platfonms. We're woridng on dead keys. 

Q. When I start a DOS window, it doesnt display at the remote 
end. 

You nught also notice the pdnterleavirig a trail of anrows behind it This 
happens when yoir DOS sessions are full-screen. WinVNC cannot re^ the 
display wfien this happens, but keystrokes shouM still get throu^. Press 
Alt-Enter to switch the DOS box to windowed mode. 

I can't type into a DOS window or any DOS apps 

This derives from the tact that Windows 95 uses BIOS calls and rxrt Windows 
messages to get keystrokes within the commaixl prompt itshouklt>e fixed in 
verston 3.3.1 R1 9 and later of the WinVNC sender, so if you're using an earlier 



iVNC server? 




If your ISP allocates you a dynamic IP address when you dial In, you will need 
to give that to the person trying to connect. On WindowsdS machines, after 
connecting, you can use the winipcf g program (type It Into the Start/Run... 
box). On NT machines, type ipconf ig at a command prompt On linux 
machines, try hostname -i. A handy new feature on recent versions of 
WinVNC causes the IP addresses of the local machine to be displayed when 
the mouse hovers over the WinVNC icon, (if they can t>e detennined at that 
time). 

Of course, if your phone line is now in use you may need to find some other 
way of getting this information to the renK)te person. I suggest a chat system 
Bke AOL Instant Messenger. There are also programs out there which win 
automatically create a web page with your current IP address, which the other 
person could then read. 

Q. Can I get rid of the taskbar icon created by WinVNC? 

No. Not without changing and recompiling the source code. We feel that there 
would be few legitimate uses of VNC where you would need to conceal its 
operation. However, there might be occasions where you would not want the 
user of the server machine to be able to adjust the WinVNC settings, 
password, etc, so versions later than 3,3.2R3 will include a 'restricted* mode 
where the icon is still visble, t>ut the menu options normally available from it 
will be disabled. 

In some situations, particularly on Win95, you may find that the icon is not 
displayed. This is not a feature, if s a bug which we plan to iron out! 

Q. Can I set up WinVNC to use my Windows NT password for 
authentication? 

Not at present Partly because there are many problems with the NT security 
nrnxlel, but chiefly because we want to keep VNC as cross-platform as 
possible. In the future we may try and make the code and the protocol more 
rrxxlular so it will t>e easier to add your own favourite authentication. 



Q. Can i malce the lUiaclntosh server start automaticaily when 
the machine boots up? 

Yes. create an alias to VNCServerarKl put it into the Startup items folder Qn 
your system fokJer). 

Q. When I try to set a new password for my Mac server, I hit 
CHANGE on the web page, but nothing happens, it is t^ng to 
bring up the settings.htmi page, but falls. 

The http portion of the current server is unstable, sorry. But you can set your 
settings with AppleScripL 

Open the AppleScript ecfitor and enter the following 

tell application •VNCServer" 
set password to *^atever" 
end tell 



ByVKutt, mouse button up events are used to ifnal to WinVNC that the 
current window may have changed and should be re*scanned* This can 
introduce a delay which results in a doubte-dick being interpreted by the 
system as a pair of single cfidcs. Variations in network delays can also cause 
the dicks to t>e too wMely separated when they appear at the server. Some 
suggestions: 

• In many situattons. the actton perfonned by.a double-dick is also 
available from a right-button menu. 

• You may find that dicking three times, rather than two, will help. 

• You can change the double-dk:k speed uang the control panel on the 
server so that more wktely*spaced dicks are still interpreted as doubles. 

• You can disable the left-dtek hook by editing the registry, as described 
In the WinVNC documentatton, although this nruiy mean that WinVNC 
misses some screen updates from that application. 

Q. rm installing WinVNC as a service on lots of machines, and f 
get prompted for the password on each one. Can I do this 
non-interactively? 

l4ot directly, but you can by editing the registry before installing. On a machine 
which already has WinVNC installed, copy ail the registry settings under 



HKEirjaSERS/ .Default /Software/ORL/WinVMC3 

into the same place in the registry of the remote machine, either by hand or 
using your tevourite tool. 

When WinVNC runs, it wiQ see the password in that sectton of the registry and 
w9l not prompt you to type one in. 

Another hint that might t>e useful was sent in l>y Johannes Norinder. If you run 
the SETUP program with a -r optk>n, it will create a setup.iss file, probably in 
your %systemroot% directory. FoDowing installatk>ns on similar conputer can 
be started with 'setup -s -h1[path to your setupiss]* and you wont have to 
answer the questions again! 

CL I only have a two-button Windows mouse, and I really need 
three buttons for X.^ 

Getversion3.3.2R10 or later of the Windows viewer. This allows you to 
emulata the middle button by pressing both buttons together. 

Q. 1 have a three-button Windows mouse, but the middle button 
doesnt work. 

TMs is almost certainly a problem with your mouse driver. The Windows VNC 
viewer recognises standard WM_MBUTTON... messages and should work with 
any driver that generates them. Some drivers, knowing that Windows seldom 
normally uses the middle button, either dont reco^ise rt. or map it to 
something else like a doU)te-cfick. Try telling Windows ttiat you have a 
different type of mouse, (weVe had reports ttidt the Ljogitech PS/2 Port Mouse 
isa good one to try) or use ttie 3-tnjtton enmilatkm mode mentioned tf)ove* 1 
tfniksome PS/2 nmise port hardware may also nod recognise the mkkSe 



you are connecting to WinVNC. doni chflB^the default settings in the 
Properties box unless you need to. See 'WinVNC is putting a huge load 
on my PC above. 
^ All the standard clients can do local rectangle copying, and this 
generally means that dragging a full window on X is much fester than 
dragging its outline. If your window manager allows this, it may speed 
things up. Roman Mitnitski also reports that when he increased the 
mouse dragging threshold (-t option of the server) the performance was 
improved. 

• Generally. wHh WinVNC, use 16-bit colour (65536 colours) on the server 
if you can. 1 6-trit is almost always the best depth to use. because: 

1 . 256-cofour screens have to be palette-converted before they can 
be transmitted to truecoiour clients. Only rf tfie client is 256-colour 
palette- based will you see any perf onmance increase. Even if the 
client is 256 colour trueookxir, ifll have to convert via a 32-bit 
truecoiour palette! - 

2. 24-bit screens have to t>e specially munged via 32-bit since 
VNC*s internal colour-handiing routines dont work with 24-bit 
directly. 

3. 24 and 32-bit screens have to have each pixel kx>ked up in three 
tatries to get the converted value. 

4. Graphics cards claiming to do 24-bit often actually do 32-bit with 
munging - this in many cases makes 24-bit slower just for general 
use than 32-bit! 

5. Hnaily, 1 6-bit involves no palette processing and a single k3okup 
in a cached srcjormat to desUfomiat table to convert the pbcels. 

On sk>w links, you may also want to use some software to compress the data 
between the two ends. SSH is good for this. See the section on security beksw. 

Q. Will VNC work through a firewall? 

It d^>ends on your firewall, and whether you want to access a server insMe 
your firewall from elsewhere, or a server outskie your firewall from inskle. 
Generally ftrswaOs are designed to prevent incoming oonneclk>ns except to 
certain well-known machines arxi ports. If you can configure these to inckjde 
your VNC server, then you wiO be able to access it from anywhere k\ the 
wofkL There is a good aigurnent to be niade for the fact that VNC is less of a 
security risk than X, so if your site doesnt aflow X in or out it may sfiH aDow 
VNC. 

Many nnodem firewalls wB allaw outgoing connectk>ns initiated from insMe, so 
ycRi can often access servers on outskie machines. It is straightforward, for 
exan^^le, to recompae the viewer source to include SOCKS support, or to 
make otfier special arrangements. Seethe contribs page, 
rfe a pity that Java within a browser doesn't auloniatically use SOCKS tf the 
browser is configured to use iL There's probably Java SOCKS support out 
there somewhere... 

ff your internet access is throu^ a router whk:h does Network Address 
Translation, you may be able to configure the router to redirect partkxilar 
knxning ports to particular machines. So you could run WinVNC with a 
<isplay number of 0 on machine snoopy, and with display 1 on machine 
Woodstock, then set your router to send port S900 to snoopy and 5901 to 
Woodstock. See t>etow for informatkm on the other port numbers used by VNC. 



Q. Which TCP/IP ports does VNC use? 



General Questions: 



Q. How do I make VNC go fester? 

We find VNC to be perfectly acceptable as our normal method of accessing 
Unix desktops on a daily baste. Thteisovera lOM/bitethemeton 
reasonably modem machines, using the X or Win32 viewer. Because 
Windows gives us fewer hints about wtiat if s doing, and because we don't 
have the source code for Windows, the NT server has to work harder to find 
out whaf 8 changed, and so a really fast machine should make a big speed 
difference. For more informatkm atXMjt how the Windows server works, see the 
WinVNC docunnentation . But if youVe been disappointed tiy the speed of the 
WirKlows server, doni give up. We're improving it gradually, though ifU be a 
while before if s as fast as on Unix. 

There are several thir>gs that can stow any VNC session down, however, and 
you may like to consider these if you firKl it too slow: 



e Unusually "bus/ desktops. The VNC protocol te very efficient a! 
rendering areas of a sin^ cotour, such as you generally find on window 
title bars, scrollbars, l>ackgrourKte of pages etc. But if, for example, you 
have pretty 24^it photographs of your girlfriend as your screen 
t>ackground, or dithered titie-l>ars on your windows, you may pay a price 
for the aesttietics. A colourful or patterned desktop background will 
probably slow down VNC more than any other eingle factor. We have 
some suggestions on speeding up the twm wirKiow manager, some of 
which wiil also apply to ottier environments. 

e Hi-colour desktops. Ooni use 24-bit colour If you can use 16 ore 
equally weB. Rememt>er. on Unfoc you can run multiple servers, so I have 
a big 1 6-bit desktop for normal work arid a small 8-bit one for when I k>g 
in from home. The server can send out a wMe range of pixel formats, and 
some viewers wiH aBow you to request a specific format for that sessk>n. 
On the Windows viewer, for exairple, if you click Optk>ns... wtien making 
the connectk>n, you can request only 8-bil pbcels from the server - 
useful if the network gets stow. Ifyouareustngamodem,lreoommerxi 
changing the shortcut In the Start menu to include the /8bit option - this 
wiil then t)e the default Similarly, if you regularly connect to a remote 
WinVNC server, conskler whether you could nin happily at tower 
resolution . A 1 280x1 024 screen has more then 4 tbnes es many pixels as 
a 640x480 one, and if all you are doir^g is checking a printer queue you 
probably dont need ttiem afil Note, ttiou^. that on WinVNC, 16-bft 
ootour is usually the best to use. See below. 

e EMerlygraphtos cards or drivers m^ make quite a difference; this is a 
graphics-intensfve appHcationi On Windows the graphics system on the 
server wiB affect the speed as well as the one on the viewer. 

e Some appications are not very economics^ about redrawing their 
display. Early verstons of Unix f4etscape, for example, terKfed to draw 
everything twice when scrolling, which did rv>thing to help the 
snrKxHhness under VNC. X1 1 Amp flashes its display very fast when in 
"pause* mode. 

e Some Java Virtual Machines are parttoularfy fast at reading from the 
network and parttaterly stow at drawing to the screen, or vice versa. 
With the Java viewer it is worth experimenting with the encodings 



ie contribs page for details. 
Q. Are you going to make it more secure? 

Whfle we do hope eventually to add better security to VNC, there's also a 
good argument for not doing so. If security is a concern, ft can be better to 
use a single system such as SSH or FreeS/WAN to encrypt all your traffic, 
rather than relying on the Individual packages to do the right thing. Then, If 
you decide that one system is too easBy crackable in a year's time, you can 
replace it yourself and all of your communications will benefit 

Q. Are you planning support for AIX» EPOC,HP-UX, SGI, Win 
3.1, or my favourite platform ? 

We have provided VNC on all the platforms we use here, and Its difficult to 
provide binaries for anything we dont have, and It takes a while to get up to 
speed on new platforms. Remember that a viewer Is available for any platform 
which runs Java, though the speed may vary quite a bit But for many 
platforms It should not be difficult to compile at least the viewer. If anyone 
tailors the sources for a particular platform we will happily either incorporate 
tfie changes in the main source distributions or make the patches available 
kom our site. Informatkxi about other people's ports of VNC to a large number 
of other platforms can be found on the 'contnl>s ' page. 

Q. Would things work better if you compressed the stream? 

Incorporates really quite efficient compressten In the sense that we 
generally send a tiny fraction of the raw data, probably something Gke 1/20 on 
m^eiage. The details are in the protocol spec if anyone^ interested. On a 
couple of test screen dumps we found that the Hextlle encocfing was more 
efficient ttian GIR I dont know whether this is true in general. 
Rit we havent done more general encoding after that; weVe tended to the 
wafw that (a) It might introduce too much latency and (b> most modems 
compress pretty wen anyway. We are planning some zlit>-compression 
«periments in the near future to see how this affects things. Because <£fferent 
WIS of the screen can be sent using (fifferent erxxxllngs. the senmcouki, in 
ttieory, detect that one bit %voukl be most efficiently sent as JPEG, while 
another would be t>etter hextiled. 
The questkm is aKveqrs how nfiuch work ITS worth 

out To some degree you can control this already, because the viewers aBow 
joo to specify your preferred encoding. Under X. if your viewer and server are 
flBTtfie same macfttne the viewer wiR use the raw ericoding by default, 
ctfhenviseitwiBuse hexHIe. You may find that by selecting different encocfings 
an. ffie command Im you get better performarKe. 

^ the suggestions above about using ssh. whfch also provkjes compresston. 

a. Have you thought about caching bits of the screen at the 
vfiewer end? 

that could also be good. You couM have an off-screen cache in the 
TOwer and the server ooukl copy things from there to the screen. 
Maoagement of this would add a certain amount of oornplexity, though. 
Stae there is already a CopyRect primrtfve in VNC, an alternative approach 

^KK/ld be to copy updates from another part of the screen If they already exist 
tee, rather than resendkig them. Again, to make the sender find out effidently 
trfien this is worth doing woukj be an interesting challenge, and volunteers for 



^^■fhportant one is 59xx. where XX is the disfi^p number. The VNC protocol 
itself runs over this port. So for most PC servers, the port will be 5900, 
because they use display 0 by default. 

In addition. VNC servers normally have a small and very restricted web server 
built in, which allows you to connect a browser to them and use the Java 
viewer. This runs on port 58xx. Note that this is the HTTP port used for 
downloading pages and applets, but once the applet is running it uses S9xx for 
VNC just like any other viewer. 

The servers can be changed to listen on ofter ports if. for any reason, these 
are not suitable for you. See the server's documentation for more details. 
Most of the viewers. If given a display number larger than 99, will interpret it as 
a direct port number arul will rK>t add 5900. 

If you are running a viewer in listening' mode, where it accepts connections 
initiated by the server, it willlisten for incoming VNC on port 5500. if s unlikely 
that this will apply to you. because the servere we cfistribute publteiy doni 
have this facility. 

Q. How secure Is VNC? 

Access to your VNC desktop generally allows access to your whole 
emnronment, so security is obvtously important VNC uses a 
challenge-response password scheme to make the initial connection, but after 
that the data is unencrypted and couM, in theory, be watched by other 
maOctous users, though ifs a bit harder to snoop a VNC session than, say, a 
telnet rtogin, or X sesskm. Since VNC nins over a simple single TCP/IP 
socket. It is easy to add support for SSL or some ottier encryption scheme if 
ttiis is important to you. Axel Bokft <axeiOuni-padertx>m.de > suggests: 
SSH allows you to redirect remote TCP/IP ports so tfiat all traffic is * 
strongly encrypted, and this can be GonMned with VNC: 
Run sshd and vnc server on machine 'sender*, ttien connect to it 
ssb 590l:server:5900fromc6ent (assuming vncserverSstensfor 
conr)ections on port 5900) and point your vnc client to clients own port 
5901. Everyttiing vnU be completely secure. [See the section in ttvs FAQ 
about port numbere if you dont understand ttie 5900/5901 references.] 
Sshd arxi ssh are free for unbc but payware for Windows. See 
http://www.es Jiutfi/ssh/ for info about SSH. 
Setting up SSH is pretty straightforward on Unbc machines, but generally harder 
on Windows. Miroslav Luptak <Miroslay.Luptakdsntsk> has posted detailed 
infbrrnation to ttie rnaifingtist about how he set his SSH system i4> on NT. See 
http://www.uk.research.altoomAff)c/archfves/ig99-03/0060J^^ for details. 
There is also a free SSH cBent for Windows available at 
htlp://www.doc.kxac.uk/--ci2/ssh . 

SSH can also conf>rBss the encrypted data * this can be very us^ if usffig 
VNC over stow nnks. Anottier nriinor issue you shouM know about ff ush^ 
Unbc viewer to connect via SSH: By default when ttie viewer connects to a 
sen/er on the k>cal machine. It uses the Vaw* pixel encoding because tMs 
generally gives better perfbnnance for local access. If this 'sender* b aduaOy 
an SSHD rediredmg ttie data to atfKJther machine, you probably warrt to 
ovenfcfo this using the ^textile option to the viewer, or you win serid a k)t rrxm 
data over the network ttian you need to. 

While we're on the subject of security, you should also be aware that only ttie 
first 8 charactere of VNC passwords are signrticant This to because ttie 
l3etpass* call used in ttie Unix sender to read a password has tills reslricfion. 
and ttie ottierpiatforms have been in»le compatible witti this. 
Ray Jones <r]onesOpoboK.com> has built a verston of VNC whkii uses 



Wkn I use VNC over a modem wlthol^CP/IP? 



Not at present, but there's no reason why it shouldnl, and we realise that this 
would be useful. VNC could mn over other transports such as RS232, firewfre, 
USB, modems etc, but at present we rely on TCP/IP. This means that you can 
use VNC over anything which supports TCP/IP, so using It over a modem is 
just the same as any other network, once you have Dial*Up Networking set 
up. If you need to communfeate directly between two machines without going 
via the internet/intranet, then set up a remote access server on one and dial in 
from the other. 

We don% at present support simple dialup without TCP, chiefly because it 
invohfes writing a lot of code to talk to the modem. Butifsonthe 'suggested 
projects • page, so any volunteers wekx>me... 

Gl Does VNC have any Y2K (Year 2000) bugs? 

The WinVNC sen^r and Windows viewer have been tested on a PC with its 
date running through the 20CX) boundary without any problems, so unless the 
underiying OS or BIOS has difficulties, VNC on a PC should be fine. The 
VhK; part of the X-based Unix VNC sender only uses dates when writing the 
log files; the logfile entries are timeslamped with a two-digit year, but the format 
is easy to change if required and the entries are not intended to be 
machine-readable. The developers of the XFreeSG server on which Xvnc is 
based state that there are no Y2K problems (see 

ht4>:/Avww jcfree86.org/FAQ/). We therefore Issue the standard disclaimer we 
believe the VNC code, in its enBrety, to be free from Year 2000 problems, 
sid)ject to the other components of the systems on which ft is running. 

Q. How can I install WinVNC on multiple machines? 

When you njn WinVNC for the first time on a machine, ft will prompt you for a 
password. If you are doing this on a large number of machines, espectaily 
remotely, this can be a nuisance. The way to bypass this is to make sure that 
the target machine already knows the password by putting the enciypted 
versfon straight Into the registry before installing. So: 

s Install WinVNC on a master machine and set the password 

• Copy the appropriate registry entries from 
HKEy_CDraENTJDSER\Sof t:ware\ORL\WinVNC3 Or 
HKEy_USERS\ .DEFAOLT\Sof tw5ire\ORI*\WinVNC3 

Of you installed WinVNC as a sen^) and instaU them on the target 
machine using your favourite registry utility. 

• Copy the VNC files (typically under C:\Program Ffles\OflL\VNC) onto the 
remote machine. 

o Install as a service or into the startup directory as appropriate. 

Q. Can I connect multiple users to the same Windows server, 
and have them each see their own desktop, as with WinPrame, 
NTrigue, WTS, etc? 

No. Windows NT has a reasonable concept of multi-user access, but not 
where the GUI is concerned. Bastealty, you cani do this without access to the 
source code of Windows, and lhafs rather diffteult to get hokl of! We have 
successfully mn multiple WinVNC servers on a Windows Temiinal Server 
machine, but they donl update unless a WTS client is also connected. whk:h 



^^urse, if your server is Unix-based, then ^Ifbve no 
run dozens of VNC senders on a single machine. 



problem. You can 



Q. Any other tips? 

Several people have indicated that they have to use Windows occasionally 
but prefer to use Unbc most of the time, and so want to access a PC under the 
desk from the Unix tx>x. 

Here's a suggestion: all other things being equal. I recommend using the 
Windows box to view the Unix machine rather than the other way around. This 
is chiefly because Windows generally works better as a cOent than as a 
server, and also because PC graphics cards are often better than those in 
Unix workstations. Remember, you can create a VNC session of any pixel 
depth you like. For my day-to-day work I use a Solaris 16-bit VNC session 
displayed on my PC. Fewof our Sun machines have more than d-bit color 
hardware, but the PC has plenty of bits to spare. 

If youYe very antf-Windows you can make your VNC desktop the same size 
as the screen and set the taskbar to 'Auto hide' and just pretend you're on an 
X terminal, but pop up the Start menu when you have to use PowerPoint... The 
Windows viewer 3.3.2R4 and later has a proper luH-screen nuxle*. so you 
doni even need to bother with auto-hkie. 

Q. You misspelled 'organization' on the download pagel 

No we dldn^ We spefl it like that In the UlC Actually, we spefl it both ways, 
but the 's* spelling is more common, despite what the OED says! Now, as for 
^isspelf... 



Compfling the source 

Q. rm trying to compile WinVNC and the compiler complains 
about various missing filesl 

You need to compile using the No_CORBA configuration, or it will tiy to 
inckide various files which are part of our internal version only. 

Q. rm having trouble compiling VNC on my platform... 

Have you checked the contribs page? Several people have provkled hints on 
how to buiW VNC on other platforms. If yours is not listed there, you might at 
least get some dues.* 



For oomments, feedbaac, etc, please see the 'Keeping ftntouch ' paga 
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Downloading VNC 

The VNC system is available for general use under the conditions of the GNU 
General Public Licence . You should be aware of the terms and conditions of 
this licence, which is also contained in the distribution itself. 

Please fill in the fomi below to download VNC. Ifs not required, but we'd be 
grateful if you filled it in. We're just curious about who's using it and what 
they're using it for. This information is purely for our own VNC-related use and 
will not be disclosed to any other party. Neither will we, in general, send any 
mail to any address given here. If you want to keep in touch with VNC 
developments after downloading, please join the mailing list. 

This page is part of the downloadable documentation; if you are looking at a 
local copy, please check the latest online version - things may have 
changedl 




Fbroomments. feedback, etc. please see the 'Keeping in touch ' page 
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Keep in touch with VNC developments 




There are several ways to keep in touch with developments in VNC: 

* Join a mailing Dst This is the most important If you dont know what 
a mailing list is or how it works, have a look at this introduction . 
There are 3 different mailing lists - you can choose the one(s) most 
approriate for your level of interest! 

vho*list ' «Kf Main list for (fu^tio^^ * 
. - .,.ri : bug reports eta' : ' : 

ync-list-digest : This carries the sanfie messages, but 
' / wilt just sand'you^ 
f'j.oontaning 

' imessagesJ You ni^^^ '] 

; ' st£uid^d;fistf:partcul^^ 
' : . Vreaderwon^ffflfar't^^^ / ** 

separate folder for ym^ \' 'i ' ' ' ' 

vno-announce ' lYiis is foranhounoeme^ 
(new) • '/ . versions of >mc, sijd5^ 

other piatforrns, availabi)tty of related • - 
. - : ^ software, This^list is ViUDdemted', . 
-./r-Y^tch mesm^ that nie^^ 
/r:! will only app€^*ff,we 
. ''^.wh/K^wawiil^^^ \.' 
• \^ C(pprbpriateibr\hel^^^ j.* 

You can add yourself to or remove yourself from the mailing lists by 
sending commands in the body of an email to 
majordomo@uk.research.attcom. For example: 

subscribe vnc-list: 

This asks for your name to be added to the list Replace Vno-lisf 
with the list of vour choice. More details will then be sent to you by 




'unsubscribe' instead of 'subscribe*, ^^ban also just send the 
command 'help*, to get more detailed instaictions. Note that these 
should be sent to 'majordomo' and not to the list Itself! If your mailer 
modifies your email address on the way out, you will be subscribed 
under this modified name, which can make unsubscribing dtfRcuR, 
particulariy if the mailer changes it to something different at a later 
time, so if you like you can specify the email address to be used: 

subscribe vnc -lis t inyaddr ess dconpany • com 

and the same appfies to unsubscribing. 
^ The archives of the mailing lists are available here, and you can 

search them here. 
^ Check these web pages regularty. If you're looking at a mlnnor of the 

main VNC site, dick here for the master version. 

• Darxus® op.net has created a VNC channel in IRC. For Information 
on how to join it, see his web page . 

• If you need to contact the developers directly, send email to 

vnc® uk.research.attcom . NOTE: Because of the level of interest In 
VNC we cannot» in general, reply to nr>essages, though we do 
promise to read them all! The mailing list is a much better method of 
contact; others may have solved your problem before, and may be 
able to help if we're not available. 

We're interested in any and all feedback, but new features & bug fixes are 
much more likely to be incorporated If you send us sample code showing 

how to accomplish tfiem! 



For cominerits, feedback, etc, please see the 'Keeping in touch' page 
Copyright 1 999 * AT&T Laboratories Cambrkjge 
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Virtual Network Computing 

ATsT 

VNC on other platforms & environments 

We prefer not to distribute binaries for platfonms we cannot test here, but 
several people have contributed source code modifications or hints to allow 
VNC to compile under different platforms. Please note that we cannot officially 
endorse or be responsible for these but we are grateful to all the contributors. 
We may try and incorporate some of these in a future source code release. If 
you port VNC to a new environment we would be grateful to hear about it; 
please post such announcements to the mailing list. 




V — 



Linux RPMs & Debian packages 

Other people have kindly packaged VNC up in RPM and Debian package 
form; see for example under V at the RPM archive 

http://rufus.w3.org/linux/RPM/ and at www.debian.org . Note that these may 
not be Identical to the standard AT&T distributions, and may not be updated as 
frequently, so you shoukJ check the main VNC site frequently. 

AIX 

Chuck Hines <chuck_hines@VNET.IBM.COM > writes: 

For anyone trying to build the latest version of VNC under AIX 4.1 .5 may be 
interested in the patch below which contains the quick and dirty changes I 
needed to do to be able to comple and link successfully (hopefully I didnt miss 
anything). Things went pretty smoothly after these minor changes and it seems 
to be running fIne.Basically the patch adds the necessary AIX sys/select.h 
inclusion where needed, removes the X1 1 R6 specific stuff, and forces 



sys/resource,h to be included. That last one left me sort of puzzled.as the way 
it was trying to build should have not tried including it at all (which should 
have been fine), but it looked like os/osinit.c WASNT including it while 
os/utils.c WAS for some unknown reason (andlhe #if logic looked correct to me 
in both files) creating undefinedsymbols. 

-Chuck 

Chuck's original patch is available here: vnc-3.3.2-aix.patch.toct and he has 
now set up a small web site with more details and binaries available. See 
http://wwwJdsl.netM>shma/chucWvnc.html . 



Acorn RISC OS 

We know of two viewers for RISC OS, 

The first, created by simon@bigblue.demon.co.uk, is avaifabte from 
http://www.blgblue.demon.co.uk/VNC.html . 

The second, by Leo White < leo@brighteyes.u-net.com > Is at 
http://www.brighteyes.u-net.com/ . 

A server for RISC OS is also available from 
http://www.interconnex.co.uk/-paul/ 



Amiga 

WA - a VNC viewer for the Amiga, which was started by J org Dietrich is now 
beingmaintainedbydspach@cybercable.fr. See his web page for more details. 

St^hane Guillard - 8tephane.guillard@steria.fr writes: 

I have set up a (incomplete, but usable) Amiga VNC server, which can be 
found on Aminet (http://de.aminetnel). as comm/tcp/AmiVNC.Iha (ie. here). 

This Is a wort< In progress. 



BeOS 

Andreas F. Bobak writes: 

Yesterday, I made a first port of the VNC viewer to the BeOS. I mixed together 
the Win32 viewer and the Unix viewer and added a bunch of BeOS specific 
stuff. It basically worics but perfomance does scream. RRE encoding is broken 
and Hextile encoding has a strange bug, but it's usable with just CoRRE and 
CopyRect. 

A snapshot of the sources and a x86 binary can be found under 
http://abstrakt.ch/be/ 

Cheers 
-boby 

— Andreas F. Bot>ak bobak@relog.ch 



BSDI 



Ill* 



Kurt Seel < kseel@utcorp.cont> writes: 

vnc compiles cleanly on bsdi 3.0 (no patches) with the following 
pecuiarity - socketc and httpd.c had to be ifdef ed like so ; 

#ifdef_bsdl 

#undef ^ANSLSOURCE 
#endif 

#include <sysAime.h> 
#«def_bsdi_ 
#define_ANSLSOURCE 1 
#endif 

It seems to work fine. The switch to xfree 3.3^ really did some good here! 
Cygwin32 

Valery Tulnikov has buiK the server and viewer under Cygwin-32» based on the 
3,3.1 patches by Sergey OkhapWn. This allows you to am the X viewer and 
server under Win32. Yes, there are some good reasons why you might want to 
do this! See http://www.dol.ru/users/valtul/ for more info. 



DOS 

Marines J. Yannlkos <mjy@pobox.com> has written a VNC viewer which runs 
under DOS, using packet drivers and the Waterioo TCP/IP library along with the 
/MIegro graphics library. The whole system including the IP stack fits 
comfortably on a floppy disk. You can get it from 
http://wvww.complang.tuwien.ac.at/nino/dosvnc.html . 

FreeBSD 

Joe Evans <evans@ittc.ukans.edu> reports: 

I compiled the VNC stuff on FreeBSD 2.2.6, and it seems to wori< fine. The only 
^ compile glitch was that you need to remove the gnumalloc library from the 
^ extra libraries list In order to do the link step. 

Bruce Mah< bmah@ca.sandia.gov> adds: 

vnc is now a part of the FreeBSD ports collection...on FreeBSD 
2.2.7-RELEASE or newer with an installed ports collection, the installation 
process is simply: 

cd /usr/ports/net/vnc 
make install 



Geos (eg. Nokia 9000) 

Marcus Groeber < mgroeber@>compuserve.cort> writes: 

I have just uploaded the first public version of the VNC Viewer for Geos 
to my home page. Have a look at 



httpy/ourwortd.compuserve.com/homepages/mgroeber/nokia.htm 

It allows you to access VNC servers from machines running Geos 3.0, 
which would be either a Nokia 9000/90001/91 1 0 Communicator, a desktop PC 
running NewDeal Office 3.0, or a Brother GeoBook notebook. 

Enjoy! 



GGi 

Steve Cheng steve@ggi-project.org writes: 

libGGI is a portable graphics library with a flexible design. See 
<http://www.ggi-project.org > for details. The graphics application can 
betransparently "retargeted" to different types of displays including X1 1 . Unux 
svgalib and fbcon. (Win32 soon to come.) The VNC targets adds the VNC 
protocol to this list. You can even run doom over VNCl :-) 

Standand VNC clients can be used with the VNC target/GGI application as the 
server. 

^ You can get It here: <http://shell.lp0line.com/-elmert/vnc.tar.g2 > 

Untar It under degas/lib/libggi of the GGI devel tree. (The stable GGI tree wont 
work because of namespace changes,eta) 

A long while ago someone wanted a "stripped-down version of the server part 
- one that skips listening/authentteation phase and just uses stdin/stdout for 
the communication (run-once application)." This is not currently done yet, but 
I have made it easy to do so. The only problem is the libGGI application trying 
to use stdin/stdout. 

[The VNC team] have asked me not to distribute this as part of libGGI (yet). (It 
has GPL'd code; the otiier parts are LGPL as the rest of UbGGI). So ft wont 
be 

in the GGI CVS tree now. 
Bug reports, fixes, and feedback welcome. 



HPUX 

Several contributors here. Kari HaWmian <hakimian@aha.com> writes: 

HPUX did not go as smoothly as some of the other OS's that have been 
reported, but I did manage to get things to compile under hpux 10.20. 

First I had to change Xvnc/config/cf/hp.cf 

Same as for 3.3.1, 1 made sure the following were set 

♦define ExtensioaOSDef ines -DHPINPUT » -DXTESTEXTl 
♦define XhpServer NO 
♦define BuildXInputzExt: NO 

♦define BuildPex NO 
♦define BuildPexExt. NO 
♦define XvncServer YES 



I also had to change the following to NO 
tdefine NeedBerklib NO 

That got things most of the way compiled. I then could not link Xvnc becuase 
of several missing objects 

limitNoFile 
1 lm± tDa t aSpa ce 
limi^StackSpace 

^ Turns out I just needed to Include sys/resource.h to two files in the 
' programs/Xserver/os directory, the following patch takes care of that. (Karl'^ 
short patch is here) 

Karl Hakimian 
hakimtan@aha.com 

And Mike Cooke writes: 

Just to Inform you I Ve managed to build the vnc suite on the following HP box 
HP-UX <name> B.I 0.20 E 9000/879 

I had major problems trying to build it with the standard HP tools and after 
much head banging and source editing. I decided to forget rt and switch to gcc 
which worked after about the 3'rd build. I applied the patches as advised In the 
contiib section on your site. 

The only further problem I had was getting the Xvnc server to recognize the 
correct fonts - somehow the aliasing config here seems a bit odd, so to get 
around that problem I just ran the x font server and it solved all the problems. 

And Ulrik Dickow <ukd@kampsax.dk> adds: 

This evening I succesfully built vnc-3.3.2r3 on HP/UX 10.20 9000/712 with 
the 

^ HP ANSI C compiler. 1 first naively tried 

xmkmf 
make Work! 
cdXvnc 
make Worid 

without any modifications to the source files, but this gave lots of errors 
in the Xvnc compilation. Then I changed hp.cf with Karls modifications from 
vnc/platfonfns.html and changed the two C files that his "short patch" 
mentions (but in a slightly improved way). This compiled succesfully, with 
only harmless warnings. To make it easier for others to build on HP/UX 10. 
IVe attached the resulting "jumbo patch" to this mail. 

It would be even easier if the changes were pemnanentiy done to the master 
source. They dont affect other platfomns than HP/UX, and I guess they'll 
help HP/UX 9 and 1 1 users too. wont they? 

To complete the helpior fellow HP/UX'ers. the second attached patch modifies 
a few lines of the vncserver Perl script to - 

a) start a CDE session if possible, othenwise fall back to the old code 

b) set the '-fp' argument reasonably for HP/UX (the CDE script will add 
more to this path). 



Due to b), the second patch should •not* be applied to the general 
distribution, although a) might be. 

somebody have problems with these plaintext unified diffs, I can provide 
^ context diffs instead, possibly in base64 or uuencoded form. I start out 
with unified diffs. since they are much shorter and much more readable In 
this case. Apply them in the top vnc source directory lil^e this: 

patch -p1 < vnc-3.3^r3_unix.ukd-kh-hpux-patch 
patch -pi < vnc-3-3ir3_unlx.ukd-hpux_specific-patch.txt 

Long live GNU patch(1) {http://www.gnu.org/). 

Thanks to ORL for conceiving a great product, and to Karl for finding out how 
to compile it on HP/UX 10. BTW, I compiled on a machine with these bundles 
^ installed, as part of an upgrade from 9.0x: 

B3393AA_APZ B.I 0.20.02 HP-UX Developer's Toolkit for 1 0.0 Series 700 
B3898AA_AP2 B.10^0.02 HP C/ANSI C Developer's Bundle for HP-UX 
10.20 (S700) 

B3910BA_APZ A.01.00 HP aC++ Compiler S700 
Ulrik*s patches are at 

http://www.uk.research.atl.eom/vnc/contrib/vnc-3.3.2r3_unix.ukd-kh-hpux-patch 
and 

http://www.uk.research.att.com/Smc/contrib/vnc-3.3^r3_unix.ukd-hpux_specific-^ 
KDE 

Markus Wuebben markus.wuebben@kde.org has built a version of the viewer 
which fits nicely into the X-based KDE environment. 

See http://studsen/er.unl-dortmund.de/-su0197/kde/kvnc/ for details. 
MacOS (alternative) 

Dair Grant <dair@webthing.net> has written an altemative Macintosh viewer 
which supports the Appearance Manager and Navigation Services, which 
means it looks more attractive on recent versions of MacOS. You can find it at 
<http://www.webthing.net/vnc.html >. 



NetBSD 

Era eriksson <era@iki.fp> wrote to tell us that information about a NetBSD port 
for 1386 is available at 

^ ftp://ftp.netbsd.0rg/pub/NetBSD/packages/pkgsn:/net/vnc/README.html 
NetWinder 

Ralph Slemsen < ralphs@netwinder.org > writes: 



IVe "ported" the server and client portions of your VNC package to our 
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NelWinder platform (an ARM-based linux system). There are only minor 
changes necessary that stem from the fact that your package tries to rebuild 
"imake" itself - but is isnt aware of the arm platform. IVe attached the patch 
below; it is against vnc-3.3J2r3 for unix. 

... We'll be providing binaries from our web site for NetWinder owners.. 
Ralph's patch is available at 

http://www.uk.research.attconrWnc/contrib/netwinder-patch.bct 



I Nokia 9000 

See 'Geos' above. 



OpenStep/Mach 

David Young (dwy@picasso.eng.ace.net) writes: 

IVe written a client for OPENSTEP/Mach (that spiffy NeXT OS) for VNC. 

It cunrently supports display at 24. 12, and 8 bpp, mouse and 
mostly-functional keyboard input (ASCII and control characters work; the 
mapping isnt yet complete and I'm looking for suggestions on how to complete 
ft), and some other client-side niceties. Encodings other than raw are on their 
way, as is NSPasteboard integration. 

rm looking for users (preferably with VNC and OPENSTEP experience) who 
can bang on this client on original NeXT boxes, Intel machines, or 
SPARCstations mnning OPENSTEP 4.2, or just people who might find it useful 
at this early state. 

OS/2 

AWra Hatakeyama <akira@sra.co.jp>is woridng on a native PM viewer. You 
can get It from http://www.sra.co.jp/people/akira/os2A^no-pm/lndex.html 

Bosse Nystr am bosse@postman.riken.go.jp has built the X viewer for OS/2 
using XFree86. He writes: 

I compiled the unix [3.3.1] sources with the attached diffs and got a woridng 
viewer under OS2 with XFree86 (and EMX). 

I tested it with servers for OSF and Win32 (rev 1 6). some problems with 
National characters for the win server otherwise it worics fine. 

— Bosse 

You can get Bosse's version from his FTP server at ftp7/bfs.riken.go.jp/pub/WiQf 
orfromTedSikorassiteat http7/lsikora.tiac.net under XFreeOS2. 



PalmPIIot 



Vladimir Minenko minenko@icsi.beri<eley.edu has created a port of the VNC 
viewer for PalmOS 2.0 or higher. 



# 





J^!^^ You can get PalmVNC from http://www.icsi.berkeley.edu/-minenko/PalmVNC 



SCO OpenServer 

Ben Maizels <bmajze!s@analystic.com> sent the patches he used to compile 
under SCO OpenServer 5. 

You can find his message at 

http://www.uk.research.att.com/vnc/contrib/sco-openserver.txt 
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SGI Irix 6.2 

Wolfram Gloger<wmglo@dent.med.uni-muenchen.de> writes: 

The following small patch was all that was necessary for me to successfully 
compile Xvnc on SGI Irix 6^ wrth the N32 binary format. A binary is available 
at ftp://ftp.dent.med.unf-muenchen.de/pub^vmglo/ , 

Wolfram's patch is available at 

http://www.uk.research.att.corn/vnc/contrib/vncHrix6.2-patch.txt 
SPARC Linux 

James Hall <ghall1@isd-net> writes: 

Just thought I would let you know: VNC 3.3.2r2 compiles just fine on 
Unux/SPARC. I am using it now to run Word and Lotus Notes without 
having to go back to my office and use my Windows 95 PC. 

To compile, I just ran the 'configure* script, then typed 'make'. I think I got a 
few warnings during the compile (mostly unused variables) but VNC runs fine. 
This was on Red Ha! Unux/SPARC 4.x, so I didnt have glibc. Dont know if 
that makes a difference. 



SunOS 4.1.3 

WeVe had reports that this buiilds witfiout any problems if you use gcc. 



SVGALIB (Linux without an X server) & Single-floppy Linux 

Ganesh Varadarajan and Sitaram Iyer have built a vncviewer which runs from a 
Linux console using the svgalib library. You will need to install svgalib and 
configure /etc/vga/libvga.config for your graphics card. Try creating senders of 
different geometries and connecting to them - if your svgalib setup doesnt work 
i for one resolution it may wort< for another. Persevere - this has a lot of 
potential, I think. Note that the cun-ent version will not generally be able to 
connect to Windows servers, because it requests a palette-based display which 
the Windows server cannot generate. 

The authors wrote: 

This is a alpha port of vncviewer to svgalib based on the [3.3.1] X client. 
You no longer need to start X to use vnc ! Even that old 4MB 386 which 
you've got in the comer can t>e used as an X terminal. It can aJso be used on 
a single-floppy Linux - not quite the answer to the QNX challenge, but good 



enough for me, 

Some hints on getting svncviewer working for you : 

1 . First of all make sure your card is supported by svgalib at the higher 
resolutions like 640x480x256. Othenvise you can only use 320x200x256 

2. Sometimes svgalib incon-ectly detects the card or doesnt detect it at all 
and defaults to the VGA driver. In this case you might have to edit 
/etc/vga/Iibvga.config (this is Redhat's svgalib config, your distribution 
might have it elsewhere) and uncomment the line conresponding to your 
chipset. Cards IVe had trouble autodetecting: Cirrus Logic 5446 - 
uncomment the chipset Cirrus line. Trident TVGA 8900 - incorrectly 
detected as Mach64. uncomment TVGA. Chips and Technologies - add 
the line chipset C&T 

(Note: It seems some distributions don*t have svgalib compiled with C&T 
support You might need to recompile svgalib). 

3. If you get something like read en-on broken pipe, it means the remote 
Xvnc has closed the connection, usually because the dienf s parameters 
like bpp are not acceptable. Check out the Xvnc togs. 

4- There is a workaround in svga.c which disables use of acceleration. You 
might want to comment out NO_ACCEL and see if acceleration works. 

5. If your mouse doesn't work, make sure that /dev/mouse is nv-able by 
you. This is because svgalib opens the mouse 0_RDWR and we give 
up suid perms immediately after vgajnit and before opening the mouse. 
Redhaf s default is 660, you might want to make this 666. 

TODO: 
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1 . The viewer Is not flexible about selection of graphics mode. It selects the 
closest possible to the server geometry/depth. It bails out if a resolution » 
server geometry Is not available. 

2. Only the std. keymap works, for other keyboards you might have to hack 
keys.h which maps Unux keycodes (different from X keycodes) to X 
keysyms. 

3. Mouse middle button doesnt work (svgalib problem ?) 

4. Keyboard LEDs 

Please mall bug reports/patches etc. to ganesh@cse.iitb.ernet.in 

In your bug report, please include the following infonriaBon: 

Linux distribution, kernel version, svgalib version. 

Graphics card and whether other svgalib apps woric at *hlgh* resolutions. 

What parameters Xvnc was started with. 

What parameters were used for svncviewer. 

Exact enror messages, snippets from log files where applicable. 

For the latest in svnc, check httpy/www.cse.iitb.emetin/-'Sitaram/vnc 

l-astly, a BIG thank you to the ORL guys for making vnc freely available. VNC 
rules ! 

Ganesh Varadarajan <ganesh@csejitb.emet.in > 

Sitaram Iyer <sitaram@cse.l'itb.ernet.ln> 

Indian Institute of Technology, Bombay. 



The sources for svncviewer are here: svno-0.1 .tgz Remember that you will need 
3 t>oth X and the VNC sources on your machine to buiki it, though you wont 




need them to run it! 
Single-floppy Unux 

Karl Heinz Kremer khk@cyberducle.com has created a single-floppy linux 
distribution which includes svncviewer. You can now use an old 486 without 
even a hard disk as an X display. See 
http://www.stuttgart.netsurf.de/-'khk/lods.html for details 

VMS 

VNC viewers for VMS 7.1 on both Vax an Alpha are available on the Law 
Bulletin Publishing Compan/s FTP server, Se the entry below for Windows 
NT/Alpha, and note the point about using a normal FTP client and not a 
browser. 



Windows CE 

The Windows CE viewer is now released! See the 
Documentation. 



Download Page and the 



Windows NT/Alpha 

John Ross Hunt <hunt@lbpc.com> writes: 

Binaries and VC++ project files are now available for Alpha NT WinVNC3.3.2. 
You can download them from: ftp://ftp.lawbulletin.comAmc/ You will probably 
have better luck downloading with a standard FTP client instead of using a 
web browser (if s a firewall issue). We plan to upgrade soon, but until then, the 
old-fashioned way worics best 

•-John Ross Hunt. L^w Bulletin Publishing Company 



For comments, feedback, etc, please see the 'Keeping in touch * page 
Copyright 1 999 - AT&T Laboratories Camlsridge 
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ANT 

VNC Extras, Add-ons and modifications 



Rrewalls 

Karl Harkimian < haldmian@aha.com> sent in a patch to compile the Unix 
viewer so that it can reach extemal servers through a SOCKS firewall. Its 
very simple, and the patch is here: socks-patch.txt . These patches apply to 
3.3.1 but they are simple enough to apply by hand to later versions. 

Obviously, you cannot access a server inside a firewall from outside without 
specially configuring the firewall; that* s what firewalls are for! Christian A. 
l^demann cal@zls.de has used an elaborate scheme: 

I have had a problem with connections from my workstation to a PC 
connected to a customers LAN, because my firewall as well as the 
customers firewall does IP-masquerading. This means that my workstation 
can only connect to the customers firewall and the customers PC can only 
connect to my 

firewall. The reason for this is, of course, to hide the complete LAN behind 
the firewali(s). 

Christian's solution involved a script listening on a single accessible 
well-known port behind the firewall, which could accept incoming 
connections and redirect them to the appropriate machine. His full details 
are here: rvnc.bct 



SSLeay encryption 

Ray Jones rjones@pobox.com has built a version of VNC which uses 
SSLeay public key encryption for a more secure connection. 

You can get it from http://web.mttedu/thouis/vnc . 



Restricting connections by IP address (TCP wrapper) 

Wolfram Gloger< wmglo@dent.med.uni-muenchen.de > writes: 

In the list archives i notice there was a discussion of implementing access 
control for Xvnc with the top wrapper library. I have now implemented this 
for 3.Z2XZ. You will need to have tcpd.h and libwrap already installed. 



Wolfram's full message is at 
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WinVNC. He writes: 

... 1 wrote some code to read a list of IPs to allow and IPs to deny from a 
text file. The njles are identical (to the best of my knowledge) to 
/etc/hosts.allow and /etc/hosts.deny on my Linux box and the text file's 
syntax is dose to that format. This is a feature which has been discussed at 
least once on the mailing fist, so I thought that you might want to add it to 
the offtciai code base. 

The x86 binaries and source code are available at: 

ftp://wik.res.cmu.edu/pubAmcip_bin.zip and 
ft|3://wik.res.cmu.edu/pub/vncip_src.zip 

I have two new files, ipauth.h and ipauth.cpp. I made some changes to 
vncclientcpp (but not the header) to use the dass and disconnect 
unauthorized clients. I also have a sample "iplist.txr file which contains the 
allowed IPs. 

The format of the text file works like this: 

<ALIX3W|DENY> <Partial/£ull IP> 
<D£N7 ALL> 

An unlimited, unordered list of IPs (or partial IPs) may be entered into the 
file like this: 

ALLOW 128.2.93. 
ALLOW 128.2.87.80 
DENY 128.220. 
DENY ALL 

In this case, the DENY 128.220. is redundant because of the DENY ALL, 
but you get the point ALLOW ALL is the default, and if the user specifies 
that, it is ignored. Allows always take precidence over denies. This code is 
not case sensitive. 

I am fairiy sure that I got rid of all of my memory leaks (I ran Purify on it, but 
I have done some slight modifications since then). I also use the fstream 
library. I don't know if you consider this to be too 
much overhead. 

- Jared Smolens 



zlib compression 

Dave DeBarr (debarr@mitre.org) has modified the X server and viewer to use 
zlib-based compression. We plan to incorporate something similar in the 
standard release before k>ng, but until then you can find his patches at 

httpy/www.uk,research.att.conrWnc/archives/1998-08/0039.html 

In addition, Dave has provided patches for the Windows viewer at 



http://www,uk,research.att.com:80Amc/archives/1998-08/0228.html 
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x2vnc 

Here's a different twist to VNC. Fredrik Hubinette hubbe@hubbe.net has 
written a VNC-based variation on the popular x2x program. If you run 
x2vnc on an X server, you can move off the side of the screen and the 
mouse nrK>vements will then be sent to a VNC server (eg. a PC sitting beside 
it) He writes: 

x2vnc is basically a stripped down version of the vncviewer but with 
slightly different goals and a very different GUI.. :) 

x2vnc emulates a 'dual head* setup by catching when the user tries to 
move the pointer past the edge of the screen. This allows me to control 
both computers from one mouse/keyboard. 

I have made x2vnc available for download from my web site: 

http://www.hubbe.net/--hubbeA(2vnc.htnil 



Enhanced Java viewer for JDK 1.1 

Muddassar Farooq <mfarooq@cse.unsw.edu.au> has produced an 
enhanced version of the Java VNC viewer. 

When run as a standalone application, it adds scroin>ars, and the abifity to 
specify 'host:display' as with the other VNC viewers. 

It uses the Java 1.1 event nxxiet, so Is 'better* Java, but wont run on older 
JVMs & browsers. 

You can get it from 

http://www.uk.research.attconrWnc/contrib/mfviewer.tar.gz . 



VncMonitor 

John Wilson < tug Owilson.co.uk > writes: 

VncMonitor is intended for those people who need to monitor several 
remote systems. A single window is used to present all the displays. The 
tab or backtab key allows the user to switch between systems. The return 
key causes the currently viewed system display to be transferred to its own 
window and the user can interact with the system using the mouse and 
keyt)oard. Closing 

the new window returns the monitored system display back to the initial 
wfrKiow. 

The configuration of VncMonitor is controlled by a fiie which contains ail 
the information about what systems are to be monitored. 

A version can be downk)aded from: 
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dialup code could be external and easily customised. 



For convnents. feedback, etc, please see the 'Keeping in touch ' paga 
Copyright 199S - AT&T Laboratories Cambriiige 
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Virtual Network Computing 



VNC people 



go to their home pages. 






Tristan 
Richardson 




Quentin 
Staf f or d-Fraser 



James 
Weather all 





Ken Wood 



Andy Barter 



Charlie 
Mcliachlan 




Paul Webster 



For comments. .eedbacK. etc. p^e see *e ' ^ 

Copyright 1909 - ATiT Lrtwratones Cambridge 



Printed copy of VNC website fvrww.uk.research.att.com/vnc) on Jun 20 1999. 
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